Share via

Relying Party Applications

  • Article

Updated: June 19, 2015

Applies To: Azure

A relying party application (also known as a claims-aware application or claims-based application) is an application or service that relies on claims for authentication. In Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS), a relying party application is a web site, an application, or a service that uses ACS to implement federated authentication.

You can create and configure relying party applications manually, by using the ACS Management Portal, or programmatically, by using the ACS Management Service.

In the ACS Management Portal, the relying party application that you add and configure is a logical representation of your web site, application, or service that trusts a specific Access Control namespace. You can add and configure many relying party applications in each Access Control namespace.

Configuring in the ACS Management Portal

You can use the ACS Management Portal to configure the following properties of a relying party application:

  • Mode

  • Realm and Return URL

  • Error URL (optional)

  • Token Format

  • Token Encryption Policy

  • Token Lifetime

  • Identity Providers

  • Rule Groups

  • Token Signing

  • Token Encryption

Mode

The Mode property determines whether you configure your relying party application settings manually or specify a WS-Federation metadata document that defines the application settings.

A WS-Federation metadata document typically contains an application's realm and return URL. It can also include an optional encryption certificate that is used to encrypt the tokens that ACS issues for the application. If a WS-Federation document is specified and the metadata contains an encryption certificate, the Token Encryption Policy setting defaults to Require Encryption. If the value of the Token Encryption Policy setting is Require Encryption, but the WS-Federation metadata document does not include an encryption certificate, you must upload an encryption certificate manually.

If your relying party application is integrated with Windows Identity Foundation (WIF), WIF automatically creates a WS-Federation metadata document for your application.

Realm and Return URL

The Realm property defines the URI in which the tokens issued by ACS are valid. The Return URL (also known as the ReplyTo address) defines the URL to which the ACS-issued tokens are sent. When a token is requested for access to the relying party application, ACS issues the token only when the realm in the token request matches the realm of the relying party application.

Important

In ACS, realm values are case-sensitive.

In the ACS Management Portal, you can configure only one realm and one return URL in each Access Control namespace. In the simplest case, the realm and Return URL are identical. For example, if the root URI of your application is https://contoso.com, the Realm and Return URL of the relying party application are https://contoso.com.

To configure more than one return URL (ReplyTo address) for a relying party application, use the RelyingPartyAddress entity in the ACS Management Service.

When a token is requested from ACS or a token is posted to ACS from an identity provider, ACS compares the realm value in the token request to the realm values for the relying party applications. If the token request uses WS-Federation protocol, ACS uses the realm value is in the wtrealm parameter. If the token uses OAuth WRAP protocol, ACS uses the realm value in the applies_to parameter. If ACS finds a matching realm in the configuration settings for a relying party application, it creates a token that authenticates the user to the relying party application and sends the token to the Return URL.

The process is the similar when the relying party has more than one Return URL. ACS gets the redirect URL from the wreply parameter. If the redirect URL is one of the Return URLs for the relying party application, ACS sends the response to that URL.

Realm values are case sensitive. The token is issued only if the realm values are identical or the realm value for the relying party application is a prefix of the realm in the token request. For example, the relying party application realm value of http://www.fabrikam.com matches a token request realm value of http://www.fabrikam.com/billing, but it does not match a token request realm v of https://fabrikam.com.

Error URL (optional)

The Error URL specifies a URL to which ACS redirects users if an error occurs during the login process. It is an optional property of the relying party application.

The Error URL value can be a custom page hosted by the relying party application, such as http://www.fabrikam.com/billing/error.aspx. As part of the redirect, ACS supplies details about the error to the relying party application as a JSON-encoded HTTP URL parameter. The custom error page can be crafted to interpret the JSON-encoded error information, to render the actual error message, and/or to display static help text.

For more information about the Error URL usage, see Code Sample: ASP.NET Simple MVC 2.

Token Format

The Token format property determines the format of the tokens that ACS issues for the relying party application. ACS can issue SAML 2.0, SAML 1.1, SWT, or JWT tokens. For more information about token formats, see Token Formats Supported in ACS.

ACS uses standard protocols to return the tokens to a web application or service. When more than one protocol is supported for a token format, ACS uses the same protocol that was used for the token request. ACS supports the following token format/protocol combinations:

  • ACS can return SAML 2.0 tokens using WS-Trust and WS-Federation protocols.

  • ACS can return SAML 1.1 tokens using WS-Federation and related WS-Trust protocols.

  • ACS can return SWT tokens using WS-Federation, WS-Trust, OAuth-WRAP, and OAuth 2.0 protocols.

  • ACS can issue and return JWT tokens using WS-Federation, WS-Trust, and OAuth 2.0 protocols.

For more information about standard protocols the ACS uses, see Protocols Supported in ACS.

When choosing a token format, consider how your Access Control namespace signs the tokens that it issues. All ACS-issued tokens must be signed. For more information, see Token Signing.

Also, consider whether you want the tokens to be encrypted.. For more information, see Token Encryption Policy.

Token Encryption Policy

The Token encryption policy determines whether the tokens that ACS issues for the relying party application are encrypted. To require encryption, select the Require Encryption value.

In ACS, you can configure an encryption policy for SAML 2.0 or SAML 1.1 tokens only. ACS does not support encryption of the SWT or JWT tokens.

ACS encrypts SAML 2.0 and SAML 1.1 tokens using an X.509 certificate containing a public key (.cer file). These encrypted tokens are then decrypted by using a private key possessed by the relying party application. For more information about getting and using encryption certificates, see Certificates and Keys.

Configuring an encryption policy on your ACS-issued tokens is optional. However, an encryption policy must be configured when your relying party application is a web service that is using proof-of-possession tokens over the WS-Trust protocol. This particular scenario does not function properly without encrypted tokens.

Token Lifetime

The Token lifetime property specifies the time interval (in seconds) during which the security token that ACS issues to the relying party application is valid. The default value is 600 (10 minutes). In ACS, the token lifetime value must be between zero (0) and 86400 (24 hours) inclusive.

Identity Providers

The Identity providers property specifies the identity providers that can send claims to the relying party application. These identity providers appear on the ACS login page for your web application or service. All identity providers configured in the Identity providers section of the ACS portal appear in the identity provider list. To add an identify provider to the list, click Identity providers.

Each relying party application can be associated with zero or more identity providers. The relying party applications in an Access Control namespace can be associated with the same identity provider or different identity providers. If you do not select any identity providers for a relying party application, you must configure a direct authentication with ACS for the relying party application. For example, you can use service identities to configure a direct authentication. For more information, see Service Identities.

Rule Groups

The Rule groups property determines which rules the relying party application uses when processing claims.

Each ACS relying party application must be associated with at least one rule group. If a token request matches a relying party application that has no rule groups, ACS does not issue a token to the web application or service.

All rule groups configured in the Rule groups section of the ACS portal appear in the rule group list. To add a rule group to the list, click Rule groups.

When you add a new relying party application in the ACS Management Portal, the Create New Rule Group option is selected by default. It is strongly recommended that you create a new rule group for your new relying party application. However, you can associate your relying party application with an existing rule group. To do so, clear the Create New Rule Group option and select the desired rule group.

You can associate a relying party application with more than one rule group (and associate a rule group with more than one relying party application). If a relying party application is associated with more than one rule group, ACS recursively evaluates the rules in all of the rule groups as though they were rules in a single rule group.

For more information about rules and rule groups, see Rule Groups and Rules.

Token Signing

The Token signing settings property specifies how the security tokens that ACS issues are signed. All ACS-issued tokens must be signed.

The token signing options that are available depend on the Token Format of the relying party application. (For more information about token formats, see Token Format.)

  • SAML tokens: Use an X.509 certificate to sign tokens.

  • SWT tokens: Use a symmetric key to sign tokens.

  • JWT tokens: Use either an X.509 certificate or a symmetric key to sign tokens.

X.509 Certificate options. The following options are available for tokens signed with an X.509 certificate.

  • Use service namespace certificate (standard)—If you select this option, ACS uses the certificate for the Access Control namespace to sign SAML 1.1 and SAML 2.0 tokens for the relying party application. Use this option if you plan to automate the configuration of your web application or service using WS-Federation metadata, because the namespace public key is published in the WS-Federation metadata for your Access Control namespace. The URL of the WS-Federation Metadata document appears on the Application Integration page of the ACS Management Portal.

  • Use dedicated certificate—If you select this option, ACS uses an application-specific certificate to sign SAML 1.1 and SAML 2.0 tokens for the relying party application. The certificate is not used for other relying party applications. After you select this option, browse for an X.509 certificate with a private key (.pfx file) and then enter the password for the .pfx file.

Note

JWT Tokens. When you configure a relying party application to use the X.509 certificate for the Access Control namespace to sign JWT tokens for a relying party application, 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.

Managed Namespaces. When you are adding a relying party application to a managed namespace, such as a Service Bus namespace, do not enter application-specific (dedicated) certificates or keys. Instead, select the options that direct ACS to use the certificates and keys that are configured for all applications in the managed namespace. For more information, see Managed Namespaces

For more information about shared and dedicated certificates and keys, see Certificates and Keys.

Symmetric key options

As a security best-practice, when using symmetric keys, create a dedicated key for each relying party application, instead of using the shared symmetric key for the Access Control namespace. If you enter or generate a dedicated key, ACS uses dedicated key to sign tokens for the relying party application as long as the dedicated key is valid. However, if the dedicated key expires and is not replaced, ACS uses the shared namespace key to sign tokens for the relying party application.

If you elect to use the shared symmetric key, copy the values for the Service Namespace key from the Certificates and keys page and paste them into the fields in the Token Signing section of the Relying party applications page.

The following options are available for tokens signed with symmetric keys.

  • Token signing key—Enter a 256-bit symmetric key or click Generate to generate a 256-bit symmetric key.

  • Effective date—Specifies the starting date of the date range during which the symmetric key is valid. Beginning on this date, ACS uses the symmetric key to sign tokens for the relying party application. The ACS default value is the current date.

  • Expiration date— Specifies the ending date of the date range during which the symmetric key is valid. From this date forward, ACS does not use the symmetric key to sign tokens for the relying party application. There is no default value. As a security best practice, symmetric keys should be replaced every year or every two years, depending on the requirements of the application.

Token Encryption

The token encryption certificate option specifies the X.509 certificate (.cer file) that is used to encrypt tokens for the relying party application. In ACS, you can encrypt only SAML 2.0 or SAML 1.1 tokens. ACS does not support encryption of SWT or JWT tokens.

You specify certificates for token encryption in the Certificates and Keys section of the ACS portal. When you click the Click here link in the Token Encryption Policy section of the Relying party application page, the Add Token Encryption Certificate page of Certificates and Keys opens. Use this page to specify a certificate file.

For more information, see Token Encryption Policy. For more information about getting and adding encryption certificates, see Certificates and Keys.

See Also

Concepts

ACS 2.0 Components