Certificates and Keys Management Guidelines

Applies To

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

Summary

This topic describes the guidelines for using certificates and keys in ACS. Because certificates and keys expire by design, it is important to track the expiration dates and take appropriate action prior to expiration so that applications that use ACS continue to function properly without interruption.

Objectives

• 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.

Overview

Because 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:

• Upload a 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 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 fail and the relying party application cannot operate properly. ACS ignores expired certificates and keys, resulting in the same exceptions that would be thrown if no certificate or key was ever configured.

The following sections provide information about managing certificates and keys that ACS uses, how to renew them and how to identify certificates and keys that are nearing expiry or have expired.

• To manage certificates and keys for Access Control namespaces and relying party applications, use the Certificates and Keys page of the ACS Management Portal. For more information about these credential types, see Certificates and Keys.

• To manage credentials (certificates, keys or passwords) of service identities, use the Service identities page of the ACS Management Portal. For more information about service identities, see Service Identities.

• To manage credentials (certificates, keys or passwords) of ACS Management Service accounts, use the Management Service page of the ACS Management Portal. For more information about the ACS Management Service, see ACS Management Service.

• To manage certificates for WS-Federation identity providers, such as AD FS 2.0, use the Identity providers page in the ACS Management Portal. For more information, see WS-Federation identity provider certificate and WS-Federation Identity Providers.

  To view and update WS-Federation identity provider certificates and keys programmatically, use the ACS Management Service. To verify the effective dates of a certificate, query the values of the StartDate and EndDate properties of the IdentityProviderKey entity. For more information, download the KeyManagement code sample, Code Sample: Key Management.

When you request a token that is signed by an expired certificate or key, ACS throws exceptions that have ACS Error Codes specific to the certificate or key. Consult the sections below for specific error codes.

Available certificates and keys

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

• 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.

Token signing certificates

ACS signs all security tokens it issues. It uses X.509 certificates to sign SAML tokens for applications.

When a signing certificate has expired, ACS returns the following errors when you request a token:

To renew a signing certificate:

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

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.

Token signing key

ACS signs all security tokens it issues. ACS uses 256-bit symmetric signing keys for applications that consumes SWT tokens issued by ACS.

When signing keys expire, ACS returns the following errors when you request a token:

To renew a signing key:

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

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 certificates

Token encryption is required when a relying party application is a web service that uses proof-of-possession tokens over the WS-Trust protocol. In other cases, token encryption is optional.

When encryption certificates expire, ACS returns the following errors when you request a token:

To renew an encryption certificate:

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

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.

Token decryption certificates

ACS can accept encrypted tokens from WS-Federation identity providers, such as AD FS 2.0. ACS uses an X.509 certificate hosted in ACS for decryption.

When decryption certificates expire, ACS returns the following errors when you request a token:

To renew a decryption certificate:

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

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 identity credentials

Service identities are credentials that are configured globally for the Access Control namespace. They allow applications or clients to authenticate directly with ACS and receive a token. An ACS service identity can be use symmetric keys, passwords, and X.509 certificates. ACS throws the following exceptions when 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. Go to the Service identities page in the ACS Management Portal.

2. Select a service identity.

3. Select a credential, symmetric key, password or X.509 certificate with an Expired or Near Expired status.

4. For a symmetric key, enter or generate a new key, and enter Effective and Expiration dates. Click Save.

5. For a password, enter a new password and enter Effective and Expiration dates. Click Save.

6. For an X.509 certificate, enter or browse to a new certificate file and then click Save.

Management Service Credentials

The ACS Management Service is a key component of ACS that allows you to programmatically manage and configure settings in an Access Control namespace. An ACS Management Service account can use symmetric keys, passwords, and an X.509 certificates. If these credentials are expired, ACS throws the following exceptions.

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

1. Go to the Management service page in the ACS Management Portal.

2. Select a management service account.

3. Select credentials, symmetric keys, passwords, or X.509 certificate with a status of Expired or Near Expired.

4. For a symmetric key, enter or generate a new key and enter Effective and Expiration dates. Click Save.

5. For a password, enter a new password and enter Effective and Expiration dates. Click Save.

6. For an X.509 certificate, enter or browse to a new certificate, and then click Save.

WS-Federation identity provider certificate

The federation metadata document for a WS-Federation identity provider includes a thumbprint that identifies the X.509 certificate that is used to sign tokens for the identify provider.

To determine whether a WS-Federation identity provider certificate is within the range of its effective dates, use the ACS Management Service or the ACS Management Portal.

To use the ACS Management Portal:

1. Log in to the Azure Management Portal https://manage.WindowsAzure.com.

2. Select an Access Control namespace and then click Manage. (Or, click Access Control Namespaces, select an Access Control namespace, and then click Manage.

3. In the ACS Management Portal, click Identity providers and then select a WS-Federation identity provider.

4. In the Token Signing Certificates section, view the effective dates and Status of the WS-Federation identity provider certificate.

5. If the certificated status is Expired or Near Expired, verify that the WS-Federation identity provider (AD FS or a custom identity provider) has added a secondary signing certificate.

   If you used a URL to identify the federation metadata for the WS-Federation identity provider, select Reimport data from WS-Federation metadata URL upon save and then click Save. If you uploaded the WS-Federation metadata as a local file, upload the new WS-Federation metadata file again and then click Save.

If ACS receives a token from an identity provider that is signed with an expired or unknown certificate, ACS throws the following exceptions.

See Also

Tasks

Code Sample: Key Management

Concepts

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