Certificates and Keys

Article
11/09/2015

Updated: June 19, 2015

Applies To: Azure

Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS) offers two different ways to sign and encrypt tokens: X.509 certificates with a private key and 256-bit symmetric keys. You can configure each certificate or key to sign tokens for particular relying party applications or for all relying party applications in the namespace, and you designate certificates and keys to be primary or secondary. To add and configure token signing, encryption, and decryption certificates and keys, use the ACS Management Service or the ACS Management Portal.

Signing Tokens

ACS signs all security tokens it issues with an X.509 certificate (with a private key) or a 256-bit symmetric key. Your choice of a signing credential type (certificate or key) depends on the token format that you select for your ACS-issued tokens. For more information, see “Token signing” in Relying Party Applications. When selecting what type of signing credential to create, consider the following:

SAML tokens are signed with X.509 certificates. SAML is the default token format used by applications built on the Windows Identity Foundation (WIF). SAML tokens can be issued over multiple protocols, such as WS-Federation and WS-Trust.
SWT tokens are signed with 256-bit symmetric keys. SWT tokens can be issued over multiple protocols, such as OAuth WRAP and WS-Federation.
JWT tokens can be signed by X.509 certificates or 256-bit symmetric keys. JWT tokens can be issued over multiple protocols, such as WS-Federation, WS-Trust, and OAuth 2.0.

Namespace or dedicated certificates and keys

You can configure a signing certificate or a symmetric key so it is used for the entire Access Control namespace or only for a particular relying party application in the namespace. The difference is as follows:

Access Control namespace —When a signing certificate or key is configured for the entire Access Control namespace, ACS uses the certificate or key to sign tokens for all relying party applications in this namespace that do not have an application-specific certificate or key. A namespace-scoped certificate is also used to sign ACS WS-Federation metadata.
Dedicated—If you configure a signing certificate or key to be used for a particular relying party application, ACS uses the signing certificate or key only to sign tokens delivered to the specified relying party application.

If you create or enter a dedicated symmetric key, ACS uses the dedicated key to sign tokens for the application. If the dedicated key expires and is not replaced, ACS uses the symmetric key for the Access Control namespace to sign tokens for the application.

Note

As a security best-practice, when using symmetric keys, create a dedicated key for each relying party application. An X.509 certificate can safely be shared by multiple applications in an Access Control namespace.
When you add a Microsoft-managed relying party application to a managed namespace, such as adding a Service Bus relying party application to a Service Bus namespace, do not use application-specific (dedicated) certificates or keys. Instead, select the ACS option to use the certificates and keys that are configured for all applications in the managed namespace. For all other relying party applications, use application-specific certificates and keys. For more information, see Managed Namespaces.
When you configure a relying party application that uses the X.509 certificate for the Access Control namespace to sign JWT tokens, links to the Access Control namespace certificate and the Access Control namespace key appear on the page for the relying party application in the ACS Management Portal. However, ACS uses only the namespace certificate to sign tokens for the relying party application.

Signing certificates are typically used to sign tokens for all relying party applications in a namespace. The public key component of a namespace signing certificate is published in the ACS WS-Federation metadata, which enables relying party applications to automate their configuration. The public keys of certificates that are assigned only to a particular relying party application are not present in the ACS WS-Federation metadata and are used only when independent control over a relying party application’s signing certificate is required.

Primary certificates and keys

In ACS, you can maintain several certificates and keys, but use only designated certificates and keys to sign tokens. The certificates and keys designated for signing are known as primary certificates and keys.

To designate a certificate or key as primary, select the Make primary item on the page for the certificate or key. To designate a different certificate as primary, select the Make primary item on the page for the other certificate or key. When you do, ACS automatically demotes any existing primary certificates or keys to non-primary.

When at least one certificate or key is primary, non-primary certificates and keys are not used for signing until they are promoted to a primary status by the administrator, even if the primary certificate or key is invalid or is expired. However, if none of the certificates (or keys) is primary, ACS uses the non-primary certificate that has the earliest valid start date.

The public key component of both primary and non-primary certificates is published in the ACS WS-Federation metadata to enable programmatic certificate rollover. However ACS only uses primary certificates and keys to sign tokens.

Effective and expiration dates of signing keys

When you add 256-bit symmetric signing keys, you must also specify an effective date and an expiration date. The effective date indicates the date that this key takes effect. The expiration date indicates the date that this key expires and cannot be used to sign tokens.

Encrypting Tokens

In ACS, you can elect to encrypt any SAML 1.1 or SAML 2.0 token that ACS issues to your relying party applications.

Important

ACS does not support encryption of SWT or JWT tokens.

Token encryption is required for web services that use proof-of-possession tokens over the WS-Trust protocol. If you use ACS to manage authentication for such a relying party application, all ACS-issued tokens for this relying party application must be encrypted. In all other scenarios, token encryption is optional.

ACS encrypts SAML tokens by using an X.509 certificate containing a public key (.cer file). The relying party application token decrypts the token by a using a private key for that X.509 certificate. For more information, see “Token encryption” in Relying Party Applications.

Decrypting tokens

ACS can accept encrypted tokens from WS-Federation identity providers, such as . The WS-Federation identity provider receives the public key of an X.509 certificate when it imports WS-Federation metadata from ACS and it uses this public key to encrypt the security token that is forwarded to ACS. ACS decrypts the token by using the private key of this X.509 certificate. For more information, see How to: Configure AD FS 2.0 as an Identity Provider.

Primary token decryption certificates

You can maintain multiple token decryption certificates for a relying party application or Access Control namespace. When you designate a certificate as primary, ACS uses that certificate to decrypt the tokens from WS-Federation identity providers, and uses non-primary certificates only if the attempt to use the primary certificate fails.

To designate a decryption certificate as primary, select the Make primary item on the page for the certificate. To designate a different certificate as primary, select the Make primary item on the page for the other certificate. When you do, ACS automatically demotes any existing primary decryption certificates to non-primary.

ACS Limitations for X.509 Certificate Files

In ACS, X.509 certificates that contain only a public key (.cer file) can be used when creating a service identity, validating a signature of an identity provider, or encrypting SAML tokens. X.509 certificate files that contain only a public key (.cer file) must be DER-encoded to be used with ACS. Base64-encoded certificate files are currently not supported. Uploading a base64-encoded certificate to ACS will result in a validation error when ACS receives an incoming token that requires that certificate.

In ACS, X.509 certificates must either be self-signed, or signed and chained directly to a public certification authority. ACS will not work with certificates that are issued by a private certification authority.

Note

X.509 ceritificates imported into ACS must not be expired.

Obtaining an X.509 Certificate

There are several ways to obtain an X.509 certificate for token signing, token encryption, or decryption. The method that you use depends on your requirements and the tools available in your organization.

Commercial Certification Authority—You can purchase an X.509 certificate from a commercial certification authority.

Generate a Self-Signed Certificate—You can generate your own self-signed certificate to use with ACS. If you are running a Windows-based operating system, you can use MakeCert.exe, a tool included in the Microsoft Windows Software Development Kit (https://go.microsoft.com/fwlink/?LinkID=214104) to generate a self-signed certificate.

For example, the following command generates a self-signed certificate in your personal certificate store.

MakeCert.exe -r -pe -n "CN=<service_namespace_name>.accesscontrol.windows.net" -sky exchange -ss my -len 2048 –e <1 year from today>

where <service_namespace_name> is the name of your Access Control namespace.

You can then export the private key from your personal store as a .pfx file and use the ACS Management Portal to upload it to ACS.

Exporting a Self-Signed Certificate

These instructions explain how to export a self-signed certification from a computer running Windows 8, Windows Server 2012, , or .

To export your self-signed certificate

Start MMC.exe and add the Certificates snap-in to your MMC console.
Double-click Certificates - Current User, Personal, and then Certificates.
Right-click a certificate, click All Tasks, and then click Export.
On the Certificate Export Wizard Welcome page, click Next.
On the Export Private Key page, select Yes, export the private key, and then click Next.
On the Export File Format page, click Personal Information Exchange - PKCS #12 (.PFX).
In the Password fields, enter a password and confirmation password, and then click Next.
In the File name field, enter a path and file name with a .pfx file name extension, and then click Next.
Click Finish.

Valid Dates of Certificates and Keys

ACS evaluates the start and end dates (and date-times) of certificates and keys in Coordinated Universal Time (UTC). As a result, ACS might consider keys and certificates to be invalid even when they are valid in the local time of the local computer or in another time zone.

To ensure that the certificate or key is valid immediately, adjust the dates to UTC time. Otherwise, ACS might fail to issue a token because the key or certificate is not yet valid.