0 out of 2 rated this helpful - Rate this topic

Certificates and Keys

Published: April 7, 2011

Updated: February 19, 2013

Applies To: Windows Azure

You can use X.509 certificates to sign, encrypt, and decrypt SAML tokens and 256-bit symmetric keys to sign SWT tokens. You can add and configure token signing, encryption, and decryption certificates and keys by using either the ACS Management Service or the ACS Management Portal.

Token Signing

ACS signs all security tokens it issues by using either 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:

X.509 certificates are used when you build an application that consumes SAML or JWT tokens issued by ACS. SAML tokens can be issued over multiple protocols, such as WS-Federation and WS-Trust. SAML is the default token format used by applications built on the Windows Identity Foundation (WIF). JWT tokens can be issued over multiple protocols, such as WS-Federation, WS-Trust, and OAuth 2.0.
256-bit symmetric signing keys are used when you build an application that consumes SWT or JWT tokens issued by ACS. SWT tokens can be issued over multiple protocols, such as OAuth WRAP and WS-Federation, and are always signed using a symmetric key. JWT tokens can be issued over multiple protocols, such as WS-Federation, WS-Trust, and OAuth 2.0 and can be signed either with an X.509 certificate or a symmetric key.

Access Control namespace versus relying party application-specific 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 this certificate or key to sign tokens delivered to all relying party applications in this namespace that do not have their own explicit certificate or key. This signing certificate (the Access Control namespace certificate) is then also used to sign the ACS WS-Federation metadata. By default, an Access Control namespace is provisioned with a default certificate and symmetric key for signing.
Relying party application—If you configure a signing certificate or key to be used for a specific relying party application, then ACS uses this signing certificate or key to sign tokens delivered only to this specified relying party application.

Note
As a security best-practice, it is recommended that symmetric keys be created for each relying party application and not be shared by multiple parties within an Access Control namespace.

Access Control namespace certificates are typically used to sign SAML tokens issued to all relying parties in a given namespace. The public key component of Access Control namespace signing certificates are published in the ACS WS-Federation metadata, which enables relying party applications to automate their configuration. Certificates assigned to a specific relying party application are not present in the ACS WS-Federation metadata and are only used in cases where independent control over a relying party application’s signing certificate is required. This is in contrast to symmetric keys, where relying party application-specific signing keys are the best practice.

Primary versus secondary token signing certificates and keys

In ACS, you can configure signing certificates and keys as primary. If you designate a certificate or a key as primary, ACS immediately begins signing tokens using this certificate or key. Designating a particular certificate or key as primary demotes any existing primary signing certificates or keys to secondary for the selected relying party application (or Access Control namespace). A secondary certificate or key is not used for signing until it is promoted to a primary status by the administrator. The public key component of both the primary and the secondary certificates is published in the ACS WS-Federation metadata to enable programmatic certificate rollover, however only primary certificates and keys are used to sign tokens issued by ACS.

If no configured token signing certificates have the “Make Primary” field checked, then the Access Control namespace will sign the token using an existing non-primary token signing certificate that has the earliest valid start date. Note that ACS will still not sign tokens with a non-primary token signing certificate if a primary certificate exists, but is invalid or is expired.

Symmetric signing keys effective and expiration dates

When adding 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 is no longer used to sign tokens.

Token Encryption

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

Important
ACS does not support encryption of the SWT or JWT tokens.

Token encryption is required if a relying party application is a web service using proof-of-possession tokens over the WS-Trust protocol. If you use ACS to broker 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 using an X.509 certificate containing a public key (.cer file). The token is then received and decrypted by a relying party application using a private key for that X.509 certificate. For more information, see “Token encryption” in Relying Party Applications.

Token Decryption

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 in this scenario. The WS-Federation identity provider receives the public key of this X.509 certificate when it imports the WS-Federation metadata from ACS and uses this public key to encrypt the security token that is forwarded to ACS. ACS then decrypts this token 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 versus secondary token decryption certificates

In ACS, you can set any token decryption certificate as a primary token decryption certificate for the given Access Control namespace. If an incoming token cannot be decrypted using the primary certificate, decryption is then attempted using any nonprimary token decryption certificates that are configured. Designating a token decryption certificate as primary demotes any existing primary decryption certificates to secondary.

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 Certificate Authority. ACS will not work with certificates that are issued by a private Certificate 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 (http://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 Your Self-Signed Certificate from a Computer Running Windows 7 or Windows Vista

To export your self-signed certificate from a computer running Windows 7 or Windows Vista

As an administrator, click Start, type the following into the Search box, and then press Enter:
mmc
In the MMC console, click File, and then click Add/Remove Snap-in.
Select Certificates, and then click Add.
Select My user account, and then click Finish.
To close the Add Standalone Snap-in dialog box, click OK.
In the console, double-click Certificates - Current User.
In the console, expand Personal, and then expand Certificates.
Right-click the certificate you created previously. Click All Tasks, and then click Export to start the Certificate Export Wizard.
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, ensure that the option Personal Information Exchange - PKCS #12 (.PFX) is selected.
In the Password fields, enter a password (twice), and then click Next.
In the File name field, enter the name of the file that you want to export, and then click Next.
Click Finish.

Validity Dates for ACS Certificates and Keys

The validity of the ACS certificates and keys that are used for token signing, encryption or decryption is measured in the ACS local time. Since it is possible that the time on a client computer that you might use to create/obtain a certificate or a key can be different than the ACS local time, it is also possible that, for example, the keys or certificates with StartDate = UtcNow may not be immediately usable.

It is recommended that you skew the effective and expiration dates of your keys or certificates if you want these keys or the certificates to be immediately valid. Otherwise you may experience random downtime with ACS, when, for example, it fails to issue a token because your signing key or certificate is not yet valid.