Appendix D
| Certificates for Browser-Based Applications - On the Issuer (Browser Scenario), Certificate for TLS/SSL (Issuer, Browser Scenario), Certificate for Token Signing (Issuer, Browser Scenario), Optional Certificate for Token Encryption (Issuer, Browser Scenario), On the Web Application Server, Certificate for TLS/SSL (Web Server, Browser Scenario), Token Signature Verification (Web Server, Browser Scenario), Token Signature Chain of Trust Verification (Web Server, Browser Scenario), Optional Token Decryption (Web Server, Browser Scenario), Cookie Encryption/Decryption (Web Server, Browser Scenario) | Certificates for Active Clients - On the Issuer (Active Scenario), Certificate for Transport Security (TLS/SSL) (Issuer, Active Scenario), Certificate for Message Security (Issuer, Active Scenario), Certificate for Token Signing (Issuer, Active Scenario), Certificate for Token Encryption (Issuer, Active Scenario), On the Web Service Host, Certificate for Transport Security (TLS/SSL) (Web Service Host, Active Scenario), Certificate for Message Security (Web Service Host, Active Scenario), Token Signature Verification (Web Service Host, Active Scenario), Token Decryption (Web Service Host, Active Scenario), Token Signature Chain Trust Verification (Web Service Host, Active Scenario), On the Active Client Host, Certificate for Message Security (Active Client Host) |
|
.png "Download code samples")
.png "Download PDF")
.png "Download Paperback")
This appendix lists the digital certificates that are used in claims-based applications. To see this in table form, see "Claims Based Identity & Access Control Guide" on CodePlex (https://claimsid.codeplex.com).
Certificates for Browser-Based Applications
In browser-based scenarios, you will find certificates used on the issuer and on the computer that hosts the web application. The client computer does not store certificates.
On the Issuer (Browser Scenario)
In browser-based scenarios, you will find the following certificates on the issuer.
Certificate for TLS/SSL (Issuer, Browser Scenario)
The Transport Layer Security protocol/Secure Sockets Layer protocol (TLS/SSL) uses a certificate to protect the communication with the issuer—for example, for the credentials transmitted to it. The purpose is to prevent man-in-the-middle attacks, eavesdropping, and replay attacks.
Requirements: The subject name in the certificate must match the Domain Name System (DNS) name of the host that provides the certificate. Browsers will generally check that the certificate has a chain of trust to one of the root authorities trusted by the browser.
Recommended certificate store: LocalMachine\My
Example: CN=login.adatumpharma.com
Certificate for Token Signing (Issuer, Browser Scenario)
The issuer's certificate for token signing is used to generate an XML digital signature to ensure token integrity and source verification.
Requirements: The worker process account that runs the issuer needs access to the private key of the certificate.
Recommended certificate store: LocalMachine\My and if Microsoft® Active Directory® Federation Services (ADFS) 2.0 is the issuer, the ADFS 2.0 database will keep a copy.
Example: CN=adatumpharma-tokensign.com
Note
The subject name on the certificate does not need to match a DNS name. It's a recommended practice to name the certificate in a way that describes its purpose.
Optional Certificate for Token Encryption (Issuer, Browser Scenario)
The certificate for token encryption secures the SAML token. Encrypting tokens is optional, but it is recommended. You may opt to rely on TLS/SSL, which will secure the whole channel.
Requirements: Only the public key is required. The private key is owned by the relying party for decrypting.
Recommended certificate store: LocalMachine\TrustedPeople, LocalMachine\AddressBook or if ADFS 2.0 is the issuer, the ADFS 2.0 database will keep it.
Example: CN=a-expense.adatumpharma-tokenencrypt.com
Note
Encrypting the token is optional, but it is generally recommended. Using TLS/SSL is already a measure to ensure the confidentiality of the token in transit. This is an extra security measure that could be used in cases where claim values are confidential.
On the Web Application Server
In browser-based scenarios, you will find the following certificates on the web application server.
Certificate for TLS/SSL (Web Server, Browser Scenario)
TLS/SSL uses a certificate to protect the communication with the web application server—for example, for the SAML token posted to it. The purpose is to prevent man-in-the-middle attacks, eavesdropping, and replay attacks.
Requirements: The subject name in the certificate must match the DNS name of the host that provides the certificate. Browsers will generally check that the certificate has a chain of trust to one of the root authorities trusted by the browser.
Recommended certificate store: LocalMachine\My
Example: CN=a-expense.adatumpharma.com
Token Signature Verification (Web Server, Browser Scenario)
The web application server has the thumbprint of the certificate that is used to verify the SAML token signature. The issuer embeds the certificate in each digitally signed security token. The web application server checks that the digital signature's thumbprint (a hash code) matches that of the signing certificate. Windows® Identity Foundation (WIF) and ADFS embed the public key in the token by default.
Requirements: The thumbprint of the issuer's certificate should be present in the <issuerNameRegistry> section of the application's Web.config file.
Recommended certificate store: None
Example: d2316a731b59683e744109278c80e2614503b17e (This is the thumbprint of the certificate with CN=adatumpharma-tokensign.com.)
Note
If the certificate (issuer public key) is embedded in the token, the signature verification is done automatically by WIF. If not, an IssuerTokenResolver needs to be configured to find the public key. This is common in interop scenarios; however, WIF and ADFS will always embed the full public key.
Token Signature Chain of Trust Verification (Web Server, Browser Scenario)
The web application server has a certificate that is used to verify the trusted certificate chain for the issuer's token signing certificate.
Requirements: The public key of the issuer certificate should be installed in LocalMachine\TrustedPeople certificate store unless the certificate was issued by a trusted root authority.
Recommended certificate store: LocalMachine\TrustedPeople only if the certificate was not issued by a trusted root authority.
Note
The chain-of-trust verification is controlled by an attribute of the <certificateValidation> element of the WIF configuration section of the application's Web.config file. WIF has this setting turned on by default.
Optional Token Decryption (Web Server, Browser Scenario)
The web application has a certificate that it uses to decrypt the SAML token that it receives from an issuer (if it was encrypted). The web application has both public and private keys. The issuer has only the public key.
Requirements: The certificate used to decrypt the SAML token should be configured in the <serviceCertificate> element of the <microsoft.identityModel> section of the application's Web.config file. Also, the App Pool account of the website should have permission to read the private key of the certificate.
Recommended certificate store: LocalMachine\My
Example: CN=a-expense.adatumpharma-tokenencrypt.com
Cookie Encryption/Decryption (Web Server, Browser Scenario)
The web application server has a certificate that it uses to ensure the confidentiality of the session cookie created to cache the token claims for the whole user session.
Requirements: The default WIF mechanism uses the Data Protection API (DPAPI) to encrypt the cookie. This requires access to a private key stored in the profile of the App Pool account. You must ensure that the account has the profile loaded by setting the Load User Profile to true in the App Pool configuration.
Recommended certificate store: None
Note
A more web farm-friendly option is to use a different CookieTransform to encrypt/decrypt the token (such as RsaEncryptionCookieTransform) that uses X.509 certificates instead of DPAPI.
Certificates for Active Clients
In scenarios with active clients that interact with web services, you will find certificates used on the issuer, on the machine that hosts the web service, and on the client machine.
On the Issuer (Active Scenario)
In active client scenarios, you will find the following certificates on the issuer.
Certificate for Transport Security (TLS/SSL) (Issuer, Active Scenario)
TLS/SSL uses a certificate to protect the communication with the issuer—for example, for the credentials transmitted to it. The purpose is to avoid man-in-the-middle attacks, eavesdropping, and replay attacks.
Requirements: The subject name in the certificate must match the DNS name of the host that provides the certificate. Browsers will generally check that the certificate has a chain of trust to one of the root authorities trusted by the browser.
Recommended certificate store: LocalMachine\My
Example: CN=login.adatumpharma.com
Certificate for Message Security (Issuer, Active Scenario)
A certificate will be used to protect the communication between the client and the issuer at the message level.
Requirements: For a custom issuer that you implement, the service credentials are configured in the Windows Communication Foundation (WCF) issuer—for example, through the <serviceCertificate> section of the issuer's Web.config file.
For an ADFS 2.0 issuer, this is configured using the Microsoft Management Console (MMC).
Recommended certificate store: LocalMachine\My or ADFS database
Example: CN=login.adatumpharma.com
Certificate for Token Signing (Issuer, Active Scenario)
The issuer's certificate for token signing is used to generate an XML digital signature to ensure token integrity and source verification.
Requirements: The worker process account that runs the issuer needs access to the private key of the certificate.
Recommended certificate store: LocalMachine\My and the ADFS 2.0 database
Example: CN=adatumpharma-tokensign.com
Note
The subject name on the certificate does not need to match a DNS name. It's a recommended practice to name the certificate in a way that describes its purpose.
Certificate for Token Encryption (Issuer, Active Scenario)
The certificate for token encryption secures the SAML token. This certificate is required when an active client is used.
Requirements: Only the public key is required on the client. The relying party owns the private key, which it uses to decrypt the SAML token.
Recommended certificate store: LocalMachine\TrustedPeople, LocalMachine\AddressBook or the ADFS 2.0 database
Example: CN=a-expense.adatumpharma-tokenencrypt.com
Note
Encrypting the token is optional, but it is generally recommended. The use of TLS/SSL is already a measure to ensure the confidentiality of the token in transit. This is an extra security measure that could be used in cases where claim values must be kept confidential.
On the Web Service Host
These are the certificates used on the machine that hosts the web service.
Certificate for Transport Security (TLS/SSL) (Web Service Host, Active Scenario)
TLS/SSL uses a certificate to protect the communication with the web service—for example, for the SAML token sent to it by an issuer. The purpose is to mitigate and prevent man-in-the-middle attacks, eavesdropping, and replay attacks.
Requirements: The subject name in the certificate must match the DNS name of the host that provides the certificate. Active clients will generally check that the certificate has a chain of trust to one of the root authorities trusted by that client.
Recommended certificate store: LocalMachine\My
Example: CN=a-expense-svc.adatumpharma.com
Certificate for Message Security (Web Service Host, Active Scenario)
A certificate will be used to protect the communication between the client and the web service at the message level.
Requirements: The service credentials are configured in the WCF web service—for example, through the <serviceCertificate> section of the web service's Web.config file.
Recommended certificate store: LocalMachine\My
Example: CN=a-expense-svc.adatumpharma.com
Token Signature Verification (Web Service Host, Active Scenario)
The web service host has the thumbprint of the certificate that is used to verify the SAML token signature. The issuer embeds the certificate in each digitally signed security token. The web service host checks that the digital signature's thumbprint (a hash code) matches that of the signing certificate. WIF and ADFS embed the public key in the token by default.
Requirements: The thumbprint of the issuer's certificate should be present in the <issuerNameRegistry> section of the web service's Web.config file.
Recommended certificate store: None
Example: d2316a731b59683e744109278c80e2614503b17e (This is the thumbprint of the certificate with CN=adatumpharma-tokensign.com.)
Note
If the certificate (issuer public key) is embedded in the token, the signature verification is done automatically by WIF. If not, an IssuerTokenResolver needs to be configured to find the public key. This is common in interop scenarios; however, WIF and ADFS will always embed the full public key.
Token Decryption (Web Service Host, Active Scenario)
The web service host has a certificate that it uses to decrypt the SAML token that it receives from an issuer. The web application has both public and private keys. The issuer has only the public key.
Requirements: The certificate used to decrypt the SAML token should be configured in the <serviceCertificate> element of the <microsoft.identityModel> section of the web service's Web.config file. Also, the App Pool account of the web server should have permission to read the private key of the certificate.
Recommended certificate store: LocalMachine\My
Example: CN=a-expense-svc.adatumpharma-tokenencrypt.com
Token Signature Chain Trust Verification (Web Service Host, Active Scenario)
The web service host has a certificate that is used to verify the trusted certificate chain for the issuer's token signing certificate.
Requirements: The public key of the issuer certificate should be installed in LocalMachine\TrustedPeople certificate store unless the certificate was issued by a trusted root authority.
Recommended certificate store: LocalMachine\TrustedPeople only if the certificate was not issued by a trusted root authority.
Note
The chain-of-trust verification is controlled by an attribute of the <certificateValidation> element of the WIF configuration section of the web service's Web.config file. WIF has this setting turned on by default.
On the Active Client Host
These are the certificates that are used on the active client computer.
Certificate for Message Security (Active Client Host)
A certificate will be used to protect the communication between the client and the web service or issuer at the message level.
Requirements: If negotiateServiceCredentials is enabled, the client will obtain the public key of the web service or issuer at run time. If not, the certificate for message security is configured in the WCF client by setting the ClientCredentials.ServiceCertificate property at run time or configuring the <serviceCertificate> element of the active client's App.config file. The service credentials are configured in the WCF web service—for example, through the <serviceCertificate> section of the web service's Web.config file.
Recommended certificate store: LocalMachine\TrustedPeople or LocalMachine\AddressBook
Example: CN=a-expense-svc.adatumpharma.com