|
| 1 | +## Provider Configuration |
| 2 | + |
| 3 | +Configure the provider with the DigiCert ONE API base URL and an API key: |
| 4 | + |
| 5 | +```hcl |
| 6 | +provider "digicert" { |
| 7 | + url = "<digicert_host_url>" # DigiCert API base URL |
| 8 | + api_key = "<digicert_api_key>" # API key for authentication |
| 9 | +} |
| 10 | +``` |
| 11 | + |
| 12 | +### Provider Arguments |
| 13 | + |
| 14 | +| Name | Description | Type | Required | |
| 15 | +|----------|--------------------------------------------------------------------------------------|--------|----------| |
| 16 | +| url | The URL pointing to the DigiCert ONE platform (e.g., "https://stage.one.digicert.com") | String | Yes | |
| 17 | +| api_key | The api key corresponding to a user’s account for authenticating to the DigiCert ONE platform | String | Yes | |
| 18 | + |
| 19 | +## Resources |
| 20 | + |
| 21 | +### Certificate Resource |
| 22 | + |
| 23 | +The `digicert_certificate` resource allows you to issue and manage certificates. |
| 24 | + |
| 25 | +#### Example with CSR |
| 26 | + |
| 27 | +```hcl |
| 28 | +resource "digicert_certificate" "example" { |
| 29 | + profile_id = "8e201a92-4b16-412d-aa5c-bbeba3dacdef" |
| 30 | + common_name = "example.com" |
| 31 | + dns_names = ["www.example.com", "api.example.com"] |
| 32 | + csr = "-----BEGIN CERTIFICATE REQUEST-----\nMIICjzCCAX/ZvGPbg=\n-----END CERTIFICATE REQUEST-----\n" |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +#### Example without CSR |
| 37 | + |
| 38 | +```hcl |
| 39 | +resource "digicert_certificate" "cert" { |
| 40 | + profile_id = "8e201a92-4b16-412d-aa5c-bbeba3dacdef" |
| 41 | + common_name = "example.com" |
| 42 | + dns_names = ["www.example.com", "api.example.com"] |
| 43 | + tags = ["production", "web-servers"] |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +### Resource Arguments |
| 48 | + |
| 49 | +| Name | Description | Type | Required | |
| 50 | +|--------------|---------------------------------------------------------------|----------------|----------| |
| 51 | +| profile_id | ID of an existing DigiCert® Trust Lifecycle Manager profile to use for certificate | String | Yes | |
| 52 | +| common_name | Common name of the certificate | String | Yes | |
| 53 | +| dns_names | SANs of the certificate, if any | List of Strings| No | |
| 54 | +| csr | Certificate Signing Request (CSR) in PEM format | String | No | |
| 55 | +| tags | Tags to attach to the certificate | List of Strings| No | |
| 56 | + |
| 57 | +After enrollment, the `digicert_certificate` resource will expose: |
| 58 | + |
| 59 | +| Name | Description | |
| 60 | +|---------------|--------------------------------------------------| |
| 61 | +| id | Unique identifier for the certificate | |
| 62 | +| serial_number | Serial number of the issued certificate | |
| 63 | +| status | Current status of the certificate | |
| 64 | +| thumbprint | SHA-1 thumbprint of the certificate | |
| 65 | +| valid_from | Certificate validity start date | |
| 66 | +| valid_to | Certificate validity end date | |
| 67 | +| certificate | Issued certificate in PEM format | |
| 68 | +| chain_pem | Certificate chain in PEM format | |
| 69 | +| request_id | Request ID for the certificate issuance | |
| 70 | + |
| 71 | +## Certificate Outputs |
| 72 | + |
| 73 | +Certificate outputs allow you to retrieve and use certificate details in your infrastructure or for verification purposes. When you define outputs, Terraform will display or make available specific certificate information after creation. |
| 74 | + |
| 75 | +### Output Example |
| 76 | + |
| 77 | +```hcl |
| 78 | +output "certificate_pem" { |
| 79 | + value = digicert_certificate.cert.certificate |
| 80 | + sensitive = true |
| 81 | +} |
| 82 | +
|
| 83 | +output "certificate_serial" { |
| 84 | + value = digicert_certificate.cert.serial_number |
| 85 | +} |
| 86 | +``` |
| 87 | +## Certificate Management |
| 88 | + |
| 89 | +### Creating Certificates |
| 90 | + |
| 91 | +1. Verify your configuration: |
| 92 | + To check if your configuration is correct, run: |
| 93 | + ``` |
| 94 | + terraform plan |
| 95 | + ``` |
| 96 | + This command: |
| 97 | +
|
| 98 | + Validates the syntax and provider settings. |
| 99 | +
|
| 100 | + Displays the changes Terraform will make without applying them. |
| 101 | +
|
| 102 | + If there are no errors, proceed to the next step. |
| 103 | +
|
| 104 | +2. Apply the configuration: |
| 105 | + To create the certificates, execute: |
| 106 | + ``` |
| 107 | + terraform apply |
| 108 | + ``` |
| 109 | + Terraform will prompt for confirmation. Type yes and press Enter to proceed. |
| 110 | +
|
| 111 | + Upon successful execution, Terraform will: |
| 112 | +
|
| 113 | + Send a request to the DigiCert® Trust Lifecycle Manager API. |
| 114 | +
|
| 115 | + Issue the requested certificates. |
| 116 | +
|
| 117 | + Store the certificate details in the Terraform state. |
| 118 | +3. View the Applied Configuration: |
| 119 | + To review the applied Terraform state, run: |
| 120 | + ``` |
| 121 | + terraform show |
| 122 | + ``` |
| 123 | +
|
| 124 | +## Revoking Certificates |
| 125 | +
|
| 126 | +There are multiple ways to revoke certificates in Terraform: |
| 127 | +
|
| 128 | +### Method 1: Remove Resource from Configuration |
| 129 | +
|
| 130 | +1. Remove the specific certificate resource from your Terraform configuration file. |
| 131 | +2. Run Terraform plan and apply: |
| 132 | + ``` |
| 133 | + terraform plan |
| 134 | + terraform apply |
| 135 | + ``` |
| 136 | + This will automatically detect the removed resource and revoke the corresponding certificate. |
| 137 | +
|
| 138 | +### Method 2: Targeted Destruction |
| 139 | +
|
| 140 | +Revoke a specific certificate by targeting its resource: |
| 141 | +
|
| 142 | +``` |
| 143 | +terraform destroy -target=digicert_certificate.example |
| 144 | +``` |
| 145 | +
|
| 146 | +### Method 3: Complete Destruction |
| 147 | +
|
| 148 | +Revoke all managed certificates: |
| 149 | +
|
| 150 | +``` |
| 151 | +terraform destroy |
| 152 | +``` |
| 153 | +(Be cautious, as this will remove the issued certificates.) |
| 154 | +
|
| 155 | +### Important Notes on Revocation |
| 156 | +
|
| 157 | +- Removing a certificate resource from the configuration or using `destroy` will trigger certificate revocation. |
| 158 | +- The certificate will be removed from both the DigiCert ONE platform and the Terraform state file. |
| 159 | +- Always use `terraform plan` before `apply` or `destroy` to preview changes. |
| 160 | +
|
| 161 | +## Security Best Practices |
| 162 | +
|
| 163 | +### Protecting Terraform State Files |
| 164 | +
|
| 165 | +The Terraform state file contains critical infrastructure information, including sensitive data. |
| 166 | +
|
| 167 | +Recommendations: |
| 168 | +- **Secure Storage**: Use remote backends with encryption and access controls: |
| 169 | + - HashiCorp's Terraform Cloud |
| 170 | + - AWS S3 with proper IAM policies |
| 171 | + - Google Cloud Storage with appropriate permissions |
| 172 | +- **Access Control**: |
| 173 | + - Restrict state file access to only necessary individuals or systems |
| 174 | + - Implement least privilege access principles |
| 175 | +
|
| 176 | +For comprehensive guidelines, refer to [HashiCorp's Sensitive Data in State documentation](https://www.terraform.io/language/state/sensitive-data). |
| 177 | +
|
| 178 | +## Troubleshooting |
| 179 | +- Error: API request failed (401 Unauthorized) |
| 180 | +
|
| 181 | + - Ensure the DigiCert ONE API key is valid and has required access. |
| 182 | +
|
| 183 | +- Error: Validation failed due to unknown attributes |
| 184 | +
|
| 185 | + - Check the DigiCert® Trust Lifecycle Manager API documentation for the correct certificate attributes. |
| 186 | +
|
| 187 | +- Error: Certificate issuance failed (400 Bad Request) |
| 188 | +
|
| 189 | + - Ensure all required fields are correctly defined in main.tf. |
| 190 | +
|
| 191 | +For more details, refer to the [DigiCert® Trust Lifecycle Manager API documentation](https://stage.one.digicert.com/mpki/docs/swagger-ui/index.html#/Inventory) or enable Terraform debugging: |
| 192 | + ``` |
| 193 | + TF_LOG=DEBUG terraform apply |
| 194 | + ``` |
| 195 | +
|
| 196 | +## Contributing |
| 197 | +
|
| 198 | +DigiCert Terraform Provider is open-source, meaning you can freely download, use, modify, and distribute it according to the terms of our license. However, this is not an open contribution project. |
| 199 | +To maintain code quality, security standards, and alignment with our internal development roadmap, we do not accept direct code contributions from external contributors. Our internal development team is solely responsible for all code changes and enhancements. |
| 200 | +
|
| 201 | +## Contact Us |
| 202 | +
|
| 203 | +If you have any questions, suggestions, or issues regarding this provider, you can contact us at terraform-provider-support@digicert.com. |
| 204 | +
|
| 205 | +## License |
| 206 | +
|
| 207 | +Copyright © 2025 DigiCert, Inc. All rights reserved. |
| 208 | +
|
| 209 | +This project is licensed under the MIT. See the [LICENSE](./LICENSE) file for more information. |
0 commit comments