Certificates and Keys Management Guidelines

• Windows Azure Active Directory Access Control (also known as Access Control Service or ACS)
  
  

This topic outlines guidelines related to certificates and keys renewal that are used in ACS. Certificates and keys are guaranteed to expire. It is important to keep track of the expiration dates and take appropriate action prior to expiration so that applications that use ACS will continue to function properly without interruptions.

Important
Track expiry and carry out rollover for certificates, keys and passwords used by the Access Control namespace, relying party applications, service identities and the ACS Management Service account.

• List the certificates and keys that must be tracked for expiration dates
  
  
• Outline the renewal procedures for the certificates and keys
  
  

  Important
  See the specific certificate, credential or key section in this topic for error messages and renewal process.

Since certificates are guaranteed to expire, it is good practice to upload a new certificate well in advance of the expiration of the current certificate. The high-level steps that should be involved are as follows:

• Uploada new secondary certificate.
  
  
• Notify the partners that use the service of the upcoming change. Partners should update their certificate configuration for their relying parties (for example, a thumbprint of the certificate configured in web.config under trustedIssuers node in an ASP.NET web application)
  
  
• Switch signing over to the new certificate (mark it primary) while leaving the previous one in place for a reasonable grace period.
  
  
• After the grace period ends, remove the old certificate. 
  
  

When a certificate or a key expires, attempts by ACS to issue tokens fails. This prevent your relying party from operating normally. Expired certificates and keys are ignored by ACS, effectively causing exceptions as if no certificate or key was ever configured. In the following sections, you will find information for each certificate and key that ACS manages, how to renew it and how to recognize if it is expired and needs to be renewed.

• Use the Certificates and Keys section of the ACS Management Portal to manage certificates and keys for Access Control namespaces and relying party applications. For more information about these credential types, see Certificates and Keys.
  
  
• Use the Service identities section of the ACS Management Portal to manage credentials (certificates, keys or passwords) related to service identities. For more information about service identities, see Service Identities.
  
  
• Use the Management Service section in the ACS Management Portal to manage credentials (certificates, keys or passwords) related to the ACS Management Service accounts. For more information about the ACS Management Service, see ACS Management Service.
  
  

There are some certificate and key types that are not visible in the ACS management portal. Specifically for WS-Federation identity providers such as AD FS, you must proactively check the validity of the certificates that the identity providers use. Currently, certificates available through WS-Federation identity providers’ metadata are not visible on the ACS management portal. To verify the validity of the certificates, you must use the management service to inspect the Effective and Expiration dates for the IdentityProviderKey’s StartDate and EndDate properties. When the certificate or a key expires, and therefore becomes invalid, ACS throws exceptions ACS Error Codes specific to the certificate or key. Consult the sections below for specific error codes.

You can update the certificates and keys programmatically by using ACS Management Service. For more information see (and download) the KeyManagement code sample, Code Sample: Management Service.

The following list displays the available certificates and keys that are used in ACS and must be tracked for expiration dates:

Important
See the specific certificate, credential or key section in this topic for error messages and renewal process.

• Token signing certificates
  
  
• Token signing keys
  
  
• Token encryption certificates
  
  
• Token decryption certificates
  
  
• Service identity credentials
  
  
• ACS Management Service account credentials
  
  
• WS-Federation identity provider signing and encryption certificates
  
  

The rest of this topic covers each certificate and key in detail.

ACS signs all security tokens it issues. X.509 certificates are used for signing when you build an application that consumes SAML tokens issued by ACS.
When signing certificates expire you will receive the following errors when trying to request a token:

To renew a signing certificate:

1. Go to the Windows Azure Management Portal, sign in, and then click Active Directory.
   
   
2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)
   
   
3. Click Certificates and Keys.
   
   
4. Select a certificate with a status of Near expired or Expired.
   
   
   
   

   Note
   In the Certificates and Keys section, certificates and keys for the Access Control namespace are labeled Service Namespace.

5. Enter or generate a certificate as required.
   
   
6. Update the Effective and Expiration dates.
   
   
7. Click Save to complete.
   
   

ACS signs all security tokens it issues. 256-bit symmetric signing keys are used when you build an application that consumes SWT tokens issued by ACS.
When signing keys expire you will receive the following errors when trying to request a token:

To renew a signing key:

1. Go to the Windows Azure Management Portal, sign in, and then click Active Directory.
   
   
2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)
   
   
3. Click Certificates and Keys.
   
   
4. Select a key with a status of Near expired or Expired.
   
   
   
   

   Note
   In the Certificates and Keys section, certificates and keys for the Access Control namespace are labeled Service Namespace.

5. Enter or generate a key as required.
   
   
6. Update the Effective and Expiration dates.
   
   
7. Click Save to complete.
   
   

Token encryption is required if a relying party application is a web service using proof-of-possession tokens over the WS-Trust protocol, in other cases token encryption is optional.
When encryption certificates expire you will receive the following errors when trying to request a token:

To renew an encryption certificate:

1. Go to the Windows Azure Management Portal, sign in, and then click Active Directory.
   
   
2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)
   
   
3. Click Certificates and Keys.
   
   
4. Select a certificate with a status of Near expired or Expired.
   
   
   
   

   Note
   In the Certificates and Keys section, certificates and keys for the Access Control namespace are labeled Service Namespace.

5. Enter or browse to the new certificate file, and then enter the password for that file.
   
   
6. Click Save to complete.
   
   

ACS can accept encrypted tokens from WS-Federation identity providers (for example, AD FS 2.0). An X.509 certificate hosted in ACS is used for decryption.
When decryption certificates expire you will receive the following errors when trying to request a token:

To renew a decryption certificate:

1. Go to the Windows Azure Management Portal, sign in, and then click Active Directory.
   
   
2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)
   
   
3. Click Certificates and Keys.
   
   
4. Use the Certificates and Keys section in the ACS Management Portal to manage certificates or keys related to Access Control namespaces and relying party applications.
   
   
5. Select a certificate with a status of Near expired or Expired.
   
   
   
   

   Note
   In the Certificates and Keys section, certificates and keys for the Access Control namespace are labeled Service Namespace.

6. Enter or browse to the new certificate file then enter the password for that file.
   
   
7. Click Save to complete.
   
   

Service identities are credentials that are configured globally for the Access Control namespace that allow applications or clients to authenticate directly with ACS and receive a token. There are three credential types that an ACS service identity can be associated with Symmetric key, Password, and X.509 certificate. Following are the exception that ACS will throw if the credentials are expired:

To verify and update expiration dates of symmetric keys or password, or to upload new certificate as service identity credentials follow instructions outlined in How to: Add Service Identities with an X.509 Certificate, Password, or Symmetric Key. List of service identity credentials available in the Edit Service Identity page.

1. Use the Service identies section in the ACS Management Portal to manage credentials (certificates, keys or passwords) related to the ACS Management Service accounts.
   
   
2. Select the Service Identity of interest.
   
   
3. Select the Credentials Symmetric Key, Password or X.509 Certificate showing as Expired or Near Expired.
   
   
4. For a Symmetric Key, enter or generate a new key, Effective and Expiration date followed by clicking Save.
   
   
5. For a Password, enter a new password, Effective and Expiration date followed by clicking Save.
   
   
6. For an X.509 Certificate, enter or browse to a new certificate file followed by clicking Save.
   
   
7. 
   
   

The ACS Management Service is a key component of ACS that allows you to programmatically manage and configure settings in an Access Control namespace. There are three credential types that the ACS Management service account can be associated with. These are symmetric key, password, and an X.509 certificate. ACS will throw out the following exceptions if these credentials are expired:

The List of the ACS Management Service account credentials is available on the Edit Management Service Account page in the ACS Management Portal.

1. Use the Management service section in the ACS Management Portal to manage credentials (certificates, keys or passwords) related to the ACS Management Service accounts.
   
   
2. Select the Management Service Account of interest.
   
   
3. Select the Credentials Symmetric Key, Password or X.509 Certificate showing as Expired or Near Expired.
   
   
4. For a Symmetric Key, enter or generate a new key, Effective and Expiration date followed by clicking Save.
   
   
5. For a Password, enter a new password, Effective and Expiration date followed by clicking Save.
   
   
6. For an X.509 Certificate, enter or browse to a new certificate file followed by clicking Save.
   
   

WS-Federation identity provider certificate is available through its metadata. When configuring WS-Federation identity provider, such as AD FS, the WS-Federation signing certificate is configured through WS-Federation metadata available via URL or as a file, read WS-Federation Identity Providers and How to: Configure AD FS 2.0 as an Identity Provider for more information. After the WS-Federation identity provider configured in ACS use ACS management service to query it for its certificates validness. Following are the exceptions that ACS will throw if the certificate is expired:

• ACS Error Codes
  
  
• ACS Management Service
  
  
• Certificates and Keys
  
  
• Service Identities
  
  
• Relying Party Applications
  
  
• How to: Add Service Identities with an X.509 Certificate, Password, or Symmetric Key
  
  

Concepts