X.509 Certificate Management
X.509 certificates are used to secure messages and tokens sent between between the OpenID provider and client.
This section describes the generation, management, and configuration of X.509 certificates used to secure OpenID Connect.
Transport Layer Security Certificates
The OpenID Connect specification recommends that all communications are over HTTPS.
As the majority of use cases see the OpenID Connect messages exchanged between the OpenID provider and client via the browser, it's important to ensure certificates for HTTPS are issued by a certificate authority (CA).
Signature and Encryption Certificates
Certificates used for signature and/or encryption support may be:
- Self-signed
- CA-issued
- Shared with HTTPS
The most appropriate option depends on security requirements, trust boundaries, cost constraints, and operational considerations.
| Decision Factor | Self-Signed Certificate | CA-Issued Certificate | HTTPS Shared Certificate |
|---|---|---|---|
| Direct Cost | None | Yes | Lower (reuses existing) |
| Issuance Time | Immediate | Delayed (CA process) | None (already issued) |
| Certificate Chain Validation | No | Yes | Yes |
| CRL / Revocation Support | No | Yes | Yes |
| Typical Lifetime | Long | Short | Short |
| Operational Complexity | Low | Medium | Medium |
| Trust Model | Explicit trust between known partners | Public trust via CA | Public trust via CA |
| Exposure if Compromised | Limited to OIDC | Limited to OIDC | Transport and OIDC |
| Recommended When | Small number of trusted partners | Strong validation and revocation required | Cost-sensitive environments with acceptable risk |
Certificate Storage
OpenID Connect configuration supports certificates stored in:
- Certificate file
- Windows certificate store
- Certificate string
- Application configuration
- Azure Key Vault
Certificate Files
Certificates may be stored on the file system as base-64 encoded or DER encoded .CER files.
A certificate and its associated private key may be stored on the file system as a .PFX file.
These are the certificate file formats supported by Windows and .NET.
A provider certificate stored on the file system may be specified in the OpenID configuration.
A provider certificate file always will be a .PFX as it must include the private key. The password protects the .PFX file.
A client certificate stored on the file system may be specified in the OpenID configuration.
A client certificate file always will be a .CER as it contains the public key only. A password is not required to protect the .CER file.
Windows Certificate Store
Certificates and their associated private keys, if any, may be stored in the Windows certificate store.
A provider certificate stored in the Windows certificate store may be specified in the OpenID configuration. The certificate must include a private key.
Ensure the application process has read permission for the private key.
The certificate may be identified by its serial number.
Alternatively, the certificate may be identified by its thumbprint.
Or the certificate may be identified by its subject name.
Similarly, a client certificate stored in the Windows certificate store may be specified in the OpenID configuration. The certificate will not include a private key.
The certificate may be identified by its serial number, thumbprint, or subject name.
Store Location and Name
By default, certificates are expected to be stored in the local machine's personal certificate store.
In a hosted environment, instead of the local machine's store, the current user store may be used.
Generally, it's recommended that certificates are stored in the personal certificate store. However, it is possible to reference certificates stored elsewhere.
Certificate Strings
Certificates may be specified as base-64 encoded strings.
This facilitates storing certificates in a database and setting OpenID configuration programmatically.
A provider certificate string may be specified in the OpenID configuration.
A provider certificate string is the base-64 encoded bytes making up the certificate and its private key. The password protects the certificate string.
PowerShell may be used to convert a PFX certificate file to a base-64 string.
For example:
A client certificate string may be specified in the OpenID configuration.
A client certificate string contains the public key only. A password is not required to protect the certificate string.
Application Configuration
Certificates may be stored as part of the application's configuration.
These certificates are accessed through IConfiguration interface and identified by configuration keys.
An optional password may be specified, if required.
The method for setting this configuration is left to the application. However, one use is to access certificates stored in an Azure Key Vault.
The configuration value is the certificate, and optionally its private key, encoded as a base-64 string.
Azure Key Vault
Certificates may be stored in an Azure Key Vault.
Applications do not have to be deployed to Azure to take advantage of an Azure Key Vault.
The Azure configuration steps are:
- Register in Azure Active Directory the application that will access the key vault.
- Create the key vault and import or generate certificates.
- Set the key vault access policies to permit the registered application to get and list the keys, secrets and certificates.
The application is responsible for establishing a connection to the key vault and retrieving certificates.
Once retrieved, the base-64 encoded certificate string must be made available through the application settings.
The certificate key specifies the application setting used to retrieve the certificate string.
A password is not required.
Key Vault Access
The application is responsible for establishing a connection to the key vault.
The recommended approach is to use the key vault configuration provider to populate the application configuration values from the Azure Key Vault.
Certificate Status
By default, any certificate specified is assumed to be available for use.
However, it is possible to identify certificates as being active, retired or for future use. This assists with certificate rollover.
Only active certificates are used for signature generation or encryption.
Retired certificates are previously active certificates that are no longer in use.
Future certificates will become active at some future point in time.
For example, the first certificate has been retired. The second certificate is active. The third certificate will become active at some point.
All certificates are included when returning the provider’s keys as part of discovery.
"ProviderCertificates": [
{
"Status": "Retired"
"SubjectName": "january-ExampleOpenIDProvider"
},
{
"Status": "Active"
"SubjectName": "may-ExampleOpenIDProvider"
},
{
"Status": "Future"
"SubjectName": "september-ExampleOpenIDProvider"
}
]
Certificate Use
By default, any certificate specified is assumed to be available for signature support and encryption support.
However, it is possible to limit the use of a certificate to only signature support or encryption support.
For example, the first certificate is used for signature generation. The second certificate is used for decryption.
"ClientCertificates": [
{
"Use": "Signature",
"SubjectName": "signature-ExampleOpenIDClient"
},
{
"Use": "Encryption",
"SubjectName": "encryption-ExampleOpenIDClient"
}
]
Certificate Rollover
Certificate rollover refers to replacing a certificate that’s about to expire or that potentially has been compromised.
Through OpenID Connect’s discovery mechanism, clients may retrieve the OpenID provider’s JSON Web Key Set (JWK) document.
This ensures clients can retrieve any new public keys associated with a certificate rollover.
Certificate Validation
By default, basic validation of certificates is performed including ensuring they haven't expired. Additional checks may be enabled through the CertificateValidationOptions.
Validation of certificate chains including checking CRLs can be a relatively expensive operation, especially if it requires off-server communications to retrieve CRLs.
Therefore, consideration must be given to the performance impact associated with certificate validation.
If further and potentially more expensive validation is required, it should be considered a separate operation that's performed on a regular basis (e.g. nightly). A revoked certificate would require re-issuance of the certificate and coordination with parties using the certificate.