Appendix E

This appendix provides background information about ACS and shows you how to obtain and configure a Microsoft Azure™ AppFabric Access Control Service (ACS) account. ACS makes it easy to authenticate and authorize website, application, and service users and is compatible with popular programming and runtime environments. It allows authentication to take place against many popular web and enterprise identity providers. Users are presented with a configurable page listing the identity providers that are configured for the application, which assists in the home realm discovery (HRD) process by permitting the user to select the appropriate identity provider.

ACS also integrates with Windows Identity Foundation (WIF) tools and environments and Microsoft Active Directory® Federation Services (ADFS) 2.0. It can accept SAML 1.1, SAML 2.0, and Simple Web Token (SWT) formatted tokens, and will issue a SAML 1.1, SAML 2.0, or SWT token. ACS supports a range of protocols that includes OAuth, OpenID, WS-Federation, and WS-Trust. Rules configured within ACS can perform protocol transition and claims transformation as required by the website, application, or service.

ACS is configured through the service interface using an OData-based management API, or though the web portal that provides a graphical and interactive administration experience.

This appendix discusses the ways that ACS can be used by showing several scenarios and the corresponding message sequences. It also contains information about creating an ACS issuer service instance, configuring applications to use this service instance, creating custom home realm discovery pages, error handling, integrating with ADFS, security considerations, and troubleshooting ACS operations.

What Does ACS DO?

ACS can be used to implement federated authentication and authorization by acting as a token issuer that authenticates users by trusting one or more identity providers. The following list contains definitions of the important entities and concepts involved in this process:

• Realm or Domain: an area or scope for which a specific identity provider is authoritative. It is not limited to only an Active Directory directory service domain or any similar enterprise mechanism. For example, the Google identity provider service is authoritative for all users in the Google realm or domain (users who have an account with Google); but it is not authoritative for users in the Windows Live® realm or domain (users with an account on the Windows Live network of Internet services).
• Home Realm Discovery: the process whereby the realm or domain of a user is identified so that the request for authentication can be forwarded to the appropriate identity provider. This may be accomplished by displaying a list of available identity providers and allowing the user to choose the appropriate one (one that will be able to authenticate the user). Alternatively, it may be achieved by asking the user to provide an email address, and then using the domain of that address to identify the home realm or domain of that user for authentication purposes.
• Identity Provider: a service or site that accepts credentials from a user. These credentials prove that the user has a valid account or identity. ACS redirects users to the appropriate identity provider that can authenticate that user and issue a token containing the claims (a specific set of information) about that user. The claims may include only a user identifier, or may include other details such as the user name, email address, and any other information that the user agrees to share. An identity provider is authoritative when the authentication takes place for a user within the provider's realm or domain.
• Security Token Service(STS)or Token Issuer: a service that issues tokens containing claims. ACS is an STS in that it issues tokens to relying parties that use ACS to perform authentication. The STS must trust the identity provider(s) it uses.
• Relying Party: an application, website, or service that uses a token issuer or STS to authenticate a user. The relying party trusts the STS to issue the token it needs. There might be several trust relationships in a chain. For example, an application trusts STS A, which in turn trusts another STS B. The application is a relying party to STS A, and STS A is a relying party to STS B.
• Trust Relationship: a configuration whereby one party trusts another party to the extent that it accepts the claims for users that the other party has authenticated. For example, in the scope of this appendix, ACS must trust the identity providers it uses and the relaying party must trust ACS.
• Transformation Rules: operations that are performed on the claims in a token received from an STS when generating the token that this entity will issue. ACS includes a rules engine that can perform a range of operations on the claims in the source token received from an identity provider or another STS. The rules can copy, process, filter, or add claims before inserting them into a token that is issued to the relying party.
• Protocol Transition: the process in an STS of issuing a token for a relying party when the original token came from another STS that implements different token negotiation protocols. For example, ACS may receive a token from an identity provider using OpenID, but issue the token to the relying party using the WS_Federation protocol.

In essence, when the user is requesting authentication in a web browser, ACS receives a request for authentication from a relying party and presents a home realm discovery page. The user selects an identity provider, and ACS redirects the user to that identity provider's login page. The user logs in and is returned to ACS with a token containing the claims this user has agreed to share in that particular identity provider.

ACS then applies the appropriate rules to transform the claims, and creates a new token containing the transformed claims. It then redirects the user back to the relying party with the ACS token. The relying party can use the claims in this token to apply authorization rules appropriate for this user.

The process for service authentication is different because there is no user interaction. Instead, the service must first obtain a suitable token from an identity provider, present this token to ACS for transformation, and then present the token that ACS issues to the relying party. The following sections of this chapter describe the message sequence in more detail, and explain how you can configure ACS to perform federated authentication.

Message Sequences for ACS

ACS can be used as a stand-alone claims issuer, but the typical scenario is to combine it with one or more local issuers such as ADFS or custom issuers. The sequence of messages and redirections varies depending on the specific scenario; however, the following are some of the more common scenarios for ACS.

ACS Authenticating Users of a Website

ACS can be used to authenticate visitors to a website when these visitors wish to use a social identity provider or another type of identity provider that ACS supports. Figure 1 shows a simplified view of the sequence of requests that occur.

Figure 1

ACS authenticating users of a website

On accessing the application (1), the visitor's web browser is redirected to ACS, the trusted source of security tokens (2 and 3). ACS displays the home realm discovery page (4) containing a list of identity providers configured for the website or web application. The user selects an identity provider and ACS redirects the visitor's web browser to that identity provider's login page (5).

After entering the required credentials, the visitor's browser is eventually redirected back to ACS (6) with the identity provider's token in the request (7). ACS performs any necessary transformation of the claims in the identity provider's token using rules configured for the website or application, and then returns a token containing these claims (8). The visitor's browser is then redirected to the claims-aware website that was originally accessed (9).

This scenario is demonstrated in Chapter 7, "Federated Identity with Multiple Partners and Microsoft Azure Access Control Service."

ACS Authenticating Services, Smart Clients, and Mobile Devices

ACS can be used to authenticate service requests for web services, smart clients, and mobile devices such as Windows Phone when the service uses a social identity provider or another type of identity provider that ACS supports. Figure 2 shows a simplified view of the sequence of requests that occur.

Figure 2

ACS authenticating services, smart clients, and SharePoint BCS

Because the service cannot use the ACS home realm discovery web page, it must be pre-configured to use the required identity provider or may query ACS to discover the trusted STS to use. The service first authenticates with the appropriate identity provider (1), which returns a token (2) that the service sends to ACS (3). ACS performs any necessary transformation of the claims in the identity provider's token using rules configured for the service, and then returns a token containing these claims (4). The service then sends the token received from ACS to the relying party service or resource (5).

This scenario is demonstrated in Chapter 8, "Claims Enabling Web Services."

Combining ACS and ADFS for Users of a Website

ACS can be used to authenticate visitors to a website when these visitors will access an ADFS STS first to establish their identity, but the ADFS STS trusts ACS so that visitors who wish to use a social identity provider or another type of identity provider can be authenticated. Figure 3 shows a simplified view of the sequence of requests that occur.

Figure 3

ACS and ADFS authenticating users of a website

Upon accessing the application (1), the visitor's web browser is redirected to ADFS (2 and 3). ADFS will contain preconfigured rules that redirect the visitor to ACS (4 and 5), which displays the home realm discovery page (6) containing a list of identity providers configured for the website or web application. The user selects an identity provider and ACS redirects the visitor's web browser to that identity provider's login page (7).

After entering the required credentials, the visitor's browser is redirected back to ACS with the identity provider's token in the request (8 and 9). ACS performs any necessary transformation of the claims in the identity provider's token using rules configured for the website or application, and then redirects the browser to ADFS with a token containing these claims (10). ADFS receives the token (11), performs any additional transformations on the claims, and returns a token (12). The visitor's browser is then redirected to the claims-aware website that was originally accessed (13).

Combining ACS and ADFS for Services, Smart Clients, and SharePoint BCS

ACS can be used to authenticate service requests for web services, smart clients, and Microsoft SharePoint® Business Connectivity Services (BCS) applications when the service uses an ADFS STS as the token issuer, but the service requires a token provided by ACS. Figure 4 shows a simplified view of the sequence of requests that occur.

Figure 4

ACS authenticating services, smart clients, and SharePoint BCS

The service is preconfigured to use ADFS and Active Directory as the identity provider. The service first authenticates through ADFS (1), which returns a token (2) that the service sends to ACS (3). ACS trusts ADFS, and performs any necessary transformation of the claims in the token using rules configured for the service; then it returns a token containing these claims (4). The service then sends the token received from ACS to the relying party service or resource (5).

This scenario is demonstrated in Chapter 9, "Securing REST Services."

Creating, Configuring, and Using an ACS Issuer

The complete process for creating and configuring an ACS account to implement a token issuer requires the following steps:

1. Access the ACS web portal.
2. Create a namespace for the issuer service instance.
3. Add the required identity providers to the namespace.
4. Configure one or more relying party applications.
5. Create claims transformations and pass-through rules.
6. Obtain the URIs for the service namespace.
7. Configure relying party applications to use ACS.

The following sections explain each of these steps in more detail.

Step 1: Access the ACS Web Portal

The initial configuration of ACS must be done using the web portal. This is a Microsoft Silverlight® browser plug-in application that provides access to the access control, service bus, and cache features of the Azure AppFabric for your account. You must log into the portal using a Windows Live ID associated with your Azure account. If you do not have a Windows Live ID, you must create and register one first at http://www.live.com. If you do not have an Azure account, you must create one at https://www.microsoft.com/windowsazure/account/ before you can use ACS.

ACS is a subscription-based service, and you will be charged for the use of ACS. The cost depends on the type of subscription you take out. At the time of writing, the standard consumption charge was $1.99 per 100,000 transactions.

Step 2: Create a Namespace for the Issuer Service Instance

After you sign into the ACS web portal, you can begin to configure your service instance. The first step is to define a namespace for your service. This is prepended to the ACS URI to provide a unique base URI for your service instance. You must choose a namespace that is not already in use anywhere else by ACS (you can check the availability before you confirm your choice), and choose a country/region where the service will be hosted.

For example, if you choose the namespace fabrikam, the base URI for your ACS service instance will be https://fabrikam.accesscontrol.appfabric.com. Endpoints for applications to use for authentication will be paths based on this unique URI.

After you have created the namespace, you see the main service management page for your new service instance. This provides quick access to the configuration settings for the trust relationships (the relying party applications, identity providers, and rule groups), the service settings (certificates, keys, and service identities), administration, and application integration.

You must use the Certificates and Keys page either to upload an X.509 certificate with a private key for use by ACS when encrypting tokens, or specify a 256-bit symmetric key. You can also upload a different certificate for signing the tokens if required. You can use certificates generated by a local certificate authority such as Active Directory Certificate Services, a certificate obtained from a commercial certification authority, or (for testing and proof of concept purposes) self-signed certificates.

Step 3: Add the Required Identity Providers to the Namespace

Next, you must specify the identity providers that you will trust to authenticate requests sent to ACS from applications and users. By default, Windows Live ID is preconfigured as an identity provider. You can add additional providers such as Google, Yahoo!, Facebook, your own or other ADFS issuers, and more. For each one, you can specify the URL of the login page and an image to display for the identity provider when the user is presented with a list of trusted providers.

For known identity providers (such as Google, Yahoo!, and Facebook) these settings are preconfigured and you should consider using the default settings. If you want to trust another identity provider, such as a Security Token Service (STS) based at an associated site such as a partner company, you must enter the login page URL, and optionally specify an image to display.

Step 4: Configure One or More Relying Party Applications

You can now configure the ACS service to recognize and respond to relying parties. Typically these are the applications and web services that will send authentication requests to this ACS service instance. For each relying party you specify:

• A name for the application or service as it will appear in the authentication portal page where users select an identity provider.

• The URIs applicable to this application or service. These include the realm (URI) for which tokens issued by ACS will be valid, the URI to redirect the request to after authentication and, optionally, a different URI to redirect the request to if an authentication error occurs.

  Note

  It is good practice to always configure the redirection addresses, even though they are mandated by ACS to be in the same realm as the token that ACS delivers, in order to mitigate interception attacks through rerouting the posted token

• The format, encryption policy, and validity lifetime (in seconds) for the tokens returned from ACS. By default the format is a SAML 2.0 token, but other formats such as SAML 1.1 and SWT are available. SAML 1.1 and SAML 2.0 tokens can be encrypted, but SWT tokens cannot. If you want to return tokens to a web service that implements the WS-Trust protocol you must select a policy that encrypts the token.

• The binding between this relying party and the identity providers you previously configured for the service namespace. Each relying party can trust a different subset of the identity providers you have configured for the service namespace.

• The token signing options. By default, tokens are signed using the certificate for the service namespace, and all relying parties will use the same certificate. However, if you wish, you can upload more certificates and allocate them to individual relying parties.

Each option in the configuration page has a "Learn more" link that provides more information on that setting. You can, as an alternative, upload a WS-Federation metadata document that contains the required settings instead of entering them manually into the portal.

Step 5: Create Claims Transformations and Pass-through Rules

By default, ACS does not include any of the claims it receives from an identity provider in the token it issues. This ensures that, by default, claims that might contain sensitive information are not automatically sent in response to authentication requests. You must create rules that pass the values in the appropriate claims through to the token that will be returned to the relying party. These rules can apply a transformation to the claim values, or simply pass the value received from the identity provider into the token.

The rules are stored in rule groups. You create a rule group and give it a name, then create individual rules for this group. The portal provides a Generate feature that will automatically generate a pass-through rule for every claim for every configured identity provider. If you do not require any transformations to take place, (which is typically the case if the relying party application or service will access ACS through another STS such as a local ADFS instance), this set of generated rules will probably suffice as all of the claims mapping and transformations will take place on the local STS issuer.

If you want to perform transformation of claims within ACS, you must create custom rules. For a custom rule, you specify:

• The rule conditions that match an input claim from an identity provider. You can specify that the rule will match on the claim type, the claim value, or both.
  • For the claim type, you can specify that it will match any claim type, one of the standard claim types exposed by this identity provider, or a specific claim type you enter (as a full XML namespace value for that claim type).
  • For the claim value, you can specify that it will match any value or a specific value you enter. Claim types and values are case-sensitive.
• The rule actions when generating the output claim. You can specify the output claim type, the output claim value, or both.
  • For the output claim type you can specify a pass-through action that generates a claim of the same type as the input claim, select one of the standard claim types exposed by this identity provider, or enter a specific claim type (as a full XML namespace value for that claim type).
  • For the output claim value you can choose to pass through the original value of the claim, or enter a value.
• The rule description (optional) that helps you to identify the rule when you come to apply it.

Step 6: Obtain the URIs for the Service Namespace

After you configure your ACS service instance, you use the Application Integration page of the portal to obtain the endpoints to which relying parties will connect to authenticate requests. This page also lists the endpoints for the management service (the API for configuring ACS without using the web portal), the OAuth WRAP URI, and the URIs of the WS-Federation and WS-Metadata Exchange documents.

Step 7: Configure Relying Party Applications to Use ACS

To add an ACS service reference to an application in Microsoft Visual Studio® development system, you must download and install the Windows Identity Foundation SDK. This adds a new option to the Visual Studio menus to allow you to add an STS reference to a project. It starts a wizard (the FedUtil utility) that asks for the URI of the WS-Federation document for your ACS service instance, with can be obtained from the application integration page of the portal in the previous step. The wizard adds a reference to the Microsoft.IdentityModel assembly to the project and updates the application configuration file.

If the application is a web application, users will be redirected to ACS when they access the application, and will see the ACS home realm discovery page that lists the configured identity providers for the application that are available. After authenticating with their chosen identity provider, users will be returned to the application, which can use the claims in the token returned by ACS to modify its behavior as appropriate for each user.

For information and links to other resources that describe techniques for using claims and tokens to apply authorization in applications and services, see "Authorization In Claims Aware Applications – Role Based and Claims Based Access Control" at https://blogs.msdn.com/b/alikl/archive/2011/01/21/authorization-in-claims-aware-applications-role-based-and-claims-based-access-control.aspx.

Custom Home Realm Discovery Pages

By default, ACS displays a home realm discovery page when a user is redirected to ACS for authentication. This page contains links to the identity providers configured for the relying party application, and is hosted within ACS. If you have configured an ADFS instance as an identity provider, you can specify email suffixes that are valid for this ADFS instance, and ACS will display a text box where users can enter an email address that has one of the valid suffixes. This enables ACS to determine the home realm for the authenticated user.

As an alternative to using the default ACS-hosted login page, you can create a custom page and host it with your application (or elsewhere). The custom page uses the Home Realm Discovery Metadata Feed exposed by ACS to get the list and details of the supported identity providers. To make this easier, you can download the example login page (which is the same as the default page) from ACS and modify it as required.

If you are integrating ACS with ADFS, the home realm discovery page will contain a text box where users can enter an email address that is valid within trusted ADFS domains. ACS will use this to determine the user's home realm. You can create a custom page that contains only a text box and does not include the list of configured identity providers if this is appropriate for your scenario.

Configuration with the Management Service API

Azure AppFabric exposes a REST-based service API in AtomPub format that uses X.509 client certificates for authentication. The URI of the management service for your ACS instance is shown in the application integration page of the web portal after your configure the instance. You can upload any valid X.509 certificate (in .cer format) to the ACS portal and then use it as a client certificate when making API requests.

The Azure management API supports all of the operations available through the web portal with the exception of creating a namespace. You can use the management API to configure identity providers, relying parties, rules, and other settings for your namespaces. To create new namespaces, you must use the web portal.

Chapter 7, "Federated Identity with Multiple Partners and Microsoft Azure Access Control Service" and the associated ACS wrapper used in this sample to configure ACS demonstrate how you can use the management API to configure identity providers, relying partiers, and rules.

For more information, see "Access Control Service Samples and Documentation" at https://acs.codeplex.com/releases/view/57595.

For examples of adding identity providers such as ADFS, OpenID, and Facebook using the management API, see the following resources:

• "Adding Identity Provider Using Management Service" at https://blogs.msdn.com/b/alikl/archive/2011/01/08/windows-azure-appfabric-access-control-service-v2-adding-identity-provider-using-management-service.aspx.
• "Programmatically Adding OpenID as an Identity Provider Using Management Service" at https://blogs.msdn.com/b/alikl/archive/2011/02/08/windows-azure-appfabric-access-control-service-acs-v2-programmatically-adding-openid-as-an-identity-provider-using-management-service.aspx.
• "Programmatically Adding Facebook as an Identity Provider Using Management Service" at https://blogs.msdn.com/b/alikl/archive/2011/01/14/windows-azure-appfabric-access-control-service-acs-v2-programmatically-adding-facebook-as-an-identity-provider-using-management-service.aspx.

Managing Errors

One of the configuration settings for a relying party that can be provided is the URI where ACS will send error messages. ACS sends details of the error as a JavaScript Object Notation (JSON)-encoded object in the response body when the original request was an OAuth request; or a SOAP fault message if the original request was a WS-Trust request. The response includes a TraceId value that is useful in identifying failed requests if you need to contact the ACS support team.

For information about handling JSON-encoded responses, see "How To: Use Error URL" at https://acs.codeplex.com/wikipage?title=How%20To%3a%20Use%20Error%20URL and "Returning Friendly Error Messages Using Error URL Feature" at https://blogs.msdn.com/b/alikl/archive/2011/01/15/windows-azure-appfabric-access-control-service-acs-v2-returning-friendly-error-messages-using-error-url-feature.aspx.

Errors that arise when processing management API requests throw an exception of type DataServiceRequestException.

A list of error codes for ACS is available from "ACS Error Codes" at https://acs.codeplex.com/wikipage?title=ACS%20Error%20Codes&version=8.

Integration of ACS and a Local ADFS Issuer

You can configure ACS to use an ADFS issuer as a trusted identity provider. This is useful in scenarios where you want users of a local application to be able to authenticate against an Active Directory installation (typically within your own organization) when they access the local application, and then access other services that require a SAML or other type of claims token. For example, a locally installed customer management application may use a partner's externally hosted service to obtain credit rating information for customers.

The procedure for configuring this scenario is to use the WS-Federation document that can be created by ADFS to configure ACS so that it can use the ADFS service as a trusted identity provider. ACS can accept encrypted tokens from ADFS identity providers as long as the appropriate X.509 certificate with a private key is hosted by ACS. The ADFS identity provider receives the public key it will use to encrypt tokens when it imports the WS-Federation metadata from ACS.

Afterwards, when users first access the local application they are authenticated by the local ADFS STS. When the application must access the externally hosted service, it queries ACS. ACS then authenticates the user against their local ADFS STS and issues a token that is valid for the remote service. The customer management application then passes this token to the remote service when it makes the call to retrieve rating information (see Figure 5).

Figure 5

ACS using an ADFS issuer as a trusted identity provider

An alternative (reverse) scenario is to configure ADFS to use ACS as a trusted issuer. In this scenario, ADFS can authenticate users that do not have an account in the local Active Directory used by ADFS. When users log into the application and are authenticated by ADFS, they can choose an identity provider supported by ACS. ADFS then accepts the token generated by ACS, optionally maps the claims it contains, and issues a suitable token (such as a Kerberos ticket) to the user that is valid in the local domain (see Figure 6).

Figure 6

ADFS using ACS as a trusted issuer

Security Considerations with ACS

You must ensure that your applications and services that make use of ACS for authentication and claims issuance maintain the requisite levels of security. Although your applications do not have access to users' login credentials, ACS does expose claims for the user that your application must manage securely.

You must ensure that credentials and certificates used by applications and services, and for access to ACS, are stored and handled in a secure manner. Always consider using SSL when passing credentials over networks. Other issues you should consider are those that apply to all applications, such as protection from spoofing, tampering, repudiation, and information disclosure.

For more information and links to related resources that describe security threats and the relevant techniques available to counter them see the following resources:

"Microsoft Azure AppFabric Access Control Service (ACS) v2 – Threats & Countermeasures" at https://blogs.msdn.com/b/alikl/archive/2011/02/03/windows-azure-appfabric-access-control-service-acs-v2-threats-amp-countermeasures.aspx

"Windows Identity Foundation (WIF) Security for ASP.NET Web Applications – Threats & Countermeasures" at https://blogs.msdn.com/b/alikl/archive/2010/12/02/windows-identity-foundation-wif-security-for-asp-net-web-applications-threats-amp-countermeasures.aspx

"Microsoft Application Architecture Guide, 2nd Edition" at https://msdn.microsoft.com/en-us/library/ff650706.aspx

Tips for Using ACS

The following advice may be useful in resolving issues encountered when using claims authentication with ACS.

ACS and STSs Generated in Visual Studio 2010

Custom STSs created from the Visual Studio 2010 template assume that the ReplyToAddress is the same as the AppliesToAddress. You can see this in in the GetScope method of the CustomSecurityTokenService, which sets scope.ReplyToAddress = scope.AppliesToAddress. In the case of ACS, the ReplyToAddress and the AppliesToAddress are different. The STS generates a redirection to the wrong place and an error occurs when an application accesses ACS to perform authentication.

To resolve this, replace the line that sets the ReplyToAddress with the following code.

if (request.ReplyTo != null)
{
    scope.ReplyToAddress = request.ReplyTo.ToString();
}
else
{
    scope.ReplyToAddress = scope.AppliesToAddress;
}

Error When Uploading a Federation Metadata Document

When adding a new ADFS token issuer as a trusted identity provider to ACS, you may receive an error such as "ACS20009: An error occurred reading the WS-Federation metadata document" when uploading the federation metadata file. ACS validates the signature of the file, and if you have modified the file that was generated by Visual Studio this error will occur. If you need to modify the metadata file, you must re-sign it. A useful tool for this can be found at "WIF Custom STS Metadata File Editor" (http://botsikas.blogspot.com/2010/06/wif-custom-sts-metadata-file-editor.html).

Avoiding Use of the Default ACS Home Realm Discovery Page

When using ACS with multiple identity providers, ACS will display a page with the list of identity providers that are configured the first time you attempt to sign in. You can avoid this by sending the appropriate whr parameter with the authentication request. The following table lists the different values for this parameter for each of the identity providers.

More Information

For more information about setting up and using ACS, see the following resources:

• "Microsoft Azure AppFabric" at https://www.microsoft.com/windowsazure/AppFabric/Overview/default.asp
• "Access Control Service Samples and Documentation" at https://acs.codeplex.com/documentation
• "Azure Team Blog" at https://blogs.msdn.com/windowsazure/

Next | Home