X.509 Certificate Management
X.509 certificates are used to secure SAML SSO and SLO between the identity provider and service provider.
This section describes the generation, management, and configuration of X.509 certificates used to secure SAML.
Transport Layer Security Certificates
The SAML specification recommends that all communications are over HTTPS.
As the majority of use cases see the SAML messages exchanged between the identity provider and service provider via the browser, it's important to ensure certificates for HTTPS are issued by a certificate authority (CA).
XML Signature and Encryption Certificates
Certificates used for XML signature and/or XML 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 SAML | Limited to SAML | Transport and SAML |
| Recommended When | Small number of trusted partners | Strong validation and revocation required | Cost-sensitive environments with acceptable risk |
Certificate Storage
SAML 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 local provider certificate stored on the file system may be specified in the SAML configuration.
A local provider certificate file always will be a .PFX as it must include the private key. The password protects the .PFX file.
A partner provider certificate stored on the file system may be specified in the SAML configuration.
A partner provider 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 local provider certificate stored in the Windows certificate store may be specified in the SAML 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 partner provider certificate stored in the Windows certificate store may be specified in the SAML 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.
"LocalCertificates": [
{
"StoreLocation": "CurrentUser"
"SerialNumber": "0867a17dc9efeabe4ccbf7e7adb7c37a"
}
]
Generally, it's recommended that certificates are stored in the personal certificate store. However, it is possible to reference certificates stored elsewhere.
"LocalCertificates": [
{
"StoreName": "WebHosting"
"SerialNumber": "0867a17dc9efeabe4ccbf7e7adb7c37a"
}
]
Certificate Strings
Certificates may be specified as base-64 encoded strings.
This facilitates storing certificates in a database and setting SAML configuration programmatically.
A local provider certificate string may be specified in the SAML configuration.
A local 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 partner provider certificate string may be specified in the SAML configuration.
A partner provider 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 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.
"LocalCertificates": [
{
"Use": "Signature",
"SubjectName": "signature-www.sp.com"
},
{
"Use": "Encryption",
"SubjectName": "encryption-www.sp.com"
}
]
Certificate Rollover
Certificate rollover refers to replacing a certificate that's about to expire or that potentially has been compromised.
Local Certificates
If a local certificate is to be rolled over, this may be done simultaneously for all partner providers, but this may present problems coordinating with each of the partner providers.
Instead, a new certificate may be introduced in a phased roll out. To achieve this, a local certificate can be specified as part of the partner provider configuration. This local certificate overrides any local certificate specified for the local provider.
In the following example, a local certificate is specified for the local service provider.
This will be used to sign SAML messages sent to partner identity providers, unless overridden by the partner identity provider configuration.
The first partner identity service provider specifies old-sp.pfx as the local certificate. This will be used to sign SAML messages sent to this partner identity provider.
The second partner identity provider specifies old-sp.pfx as the local certificate. This will be used to sign SAML messages sent to this partner identity provider.
The third partner identity provider doesn't specify a local certificate. Therefore, new-sp.pfx, which is specified in the local service provider configuration, will be used to sign SAML messages sent to this partner identity provider.
"LocalServiceProviderConfiguration": {
"Name": "http://ExampleServiceProvider",
"LocalCertificates": [
{
"FileName": "certificates/new-sp.pfx",
"Password": "password"
}
]
},
"PartnerIdentityProviderConfigurations": [
{
"Name": "http://ExampleIdentityProvider1",
"LocalCertificates": [
{
"FileName": "certificates/old-sp.pfx",
"Password": "password"
}
],
"PartnerCertificates": [
{
"FileName": "certificates/idp1.cer"
}
]
},
{
"Name": "http://ExampleIdentityProvider2",
"LocalCertificates": [
{
"FileName": "certificates/old-sp.pfx",
"Password": "password"
}
],
"PartnerCertificates": [
{
"FileName": "certificates/idp2.cer"
}
]
},
{
"Name": "http://ExampleIdentityProvider3",
"PartnerCertificates": [
{
"FileName": "certificates/idp3.cer"
}
]
}
]
To support phased rollout of a new certificate, it could be specified as the local certificate for the local provider and the old certificate is specified as the local certificate for each partner provider. As partner providers are ready to switch to the new certificate, the local certificate specifications for these partner providers are removed so that the new certificate is then used.
Partner Certificates
If a partner provider certificate is being rolled over, this may present problems coordinating with the partner provider.
To avoid any issues, both the old and new partner provider certificate may be specified.
In the following example, both the old and new certificates are specified for the partner provider.
If a signed SAML message is received from the partner provider, the first certificate is used to attempt to verify the signature. If that fails, the second certificate is used.
"PartnerIdentityProviderConfigurations": [
{
"Name": "http://ExampleIdentityProvider1",
"PartnerCertificates": [
{
"FileName": "certificates/idp1-old.cer"
},
{
"FileName": "certificates/idp1-new.cer"
}
]
}
]
Once successful rollover of the partner provider's certificate has been confirmed, the configuration should be updated to remove the old certificate.
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 during SSO.
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 partner providers using the certificate.
Generating Self-Signed Certificates
The CreateSelfSignedCert console application project may be used to create a self-signed certificate.
It will prompt for various input required to create the certificate.
Subject distinguished name (eg CN=test):
The subject distinguished name (DN) is identifying information embedded in the certificate. The simplest DN is a common name (CN) whose format is "CN=
A CN identifying your organization or application is recommended.
Key Size in bits [2048]:
Specify the key size.
Number of years before expiring [5]:
Specify the number of years before the certificate expires.
Certificate file name (eg test.cer):
Specify the certificate file name.
Private key file name (eg test.pfx):
Specify the private key file name.
Private key password:
Specify a password to protect the private key.