Export (0) Print
Expand All

Certificates and Keys Management Guidelines

Updated: February 21, 2014

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

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.

ImportantImportant
Track expiry and renew 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

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

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.

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

ImportantImportant
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. 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:

 

Error Code Message Remedy

ACS50004

No primary X.509 signing certificate is configured. A signing certificate is required for SAML.

If the chosen relying party uses SAML tokens, ensure that a valid X.509 certificate is configured for the relying party or the Access Control namespace. The certificate must be set to primary and must not be expired.

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.



    noteNote
    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. 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:

 

Error Code Message Remedy

ACS50003

No primary symmetric signing key is configured. A symmetric signing key is required for SWT.

If the chosen relying party uses SWT as its token type, ensure that a symmetric key is configured for the relying party or the Access Control namespace, and that the key is set to primary and is not expired.

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.



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

 

Error Code Message Remedy

ACS50005

Token encryption is required but no encrypting certificate is configured for the relying party.

Either disable token encryption for the chosen relying party or upload an X.509 certificate to be used for token encryption.

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.



    noteNote
    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, 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:

 

Error Code Message

ACS10001

An error occurred while processing the SOAP header.

ACS20001

An error occurred while processing a WS-Federation sign-in response.

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.



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

 

Credential Error Code Message Remedy

Symmetric key, Password

ACS50006

Signature verification failed. (M Details are in the message.)

X.509 Certificate

ACS50016

X509Certificate with subject '<Certificate subject name>' and thumbprint '<Certificate thumbprint>' does not match any configured certificate.

Ensure that the requested certificate has been uploaded to ACS.

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.

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.

 

Credential Error Code Message Remedy

Symmetric key or Password

ACS50006

Signature verification failed. (There may be more details in the message.)

X.509 Certificate

ACS50016

X509Certificate with subject '<Certificate subject name>' and thumbprint '<Certificate thumbprint>' does not match any configured certificate.

Ensure that the requested certificate has been uploaded to ACS.

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.

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.

 

Error Code Message

ACS10001

An error occurred while processing the SOAP header.

ACS20001

An error occurred while processing a WS-Federation sign-in response.

ACS50006

Signature verification failed. (There may be more details in the message.)

See Also

Community Additions

ADD
Show:
© 2014 Microsoft