Appendix B - Authenticating Users and Authorizing Requests

patterns & practices Developer Center

On this page:
Uses Cases and Challenges | Authenticating Public Users | Authenticating Corporate Users and Users from Partner Organizations | Authorizing User Actions | Authorizing Service Access for Non-Browser Clients | Authorizing Access to Service Bus Queues | Authorizing Access to Service Bus Relay Endpoints | Cross-Cutting Concerns | Security | Responsiveness | Reliability | Interoperability | Claims-Based Authentication and Authorization Technologies | Federated Authentication - An Overview of the Claims-Based Authentication Process, Authorizing Web Service Requests | Windows Identity Foundation | Azure Access Control Service - ACS and Unique User IDs | Azure Service Bus Authentication and Authorization | Client Authentication - Service Bus Tokens and Token Providers | Service Bus Endpoints and Relying Parties | Authorization Rules and Rule Groups | More Information

Most applications will need to authenticate and authorize visitors or partners at some stage of the process. Traditionally, authentication was carried out against a local application-specific store of user details, but increasingly users expect applications to allow them to use more universal credentials; for example, existing accounts with social network identity providers such as Windows Live, Google, Facebook, and Open ID.

This process, called federated authentication, also offers the opportunity for applications to support single sign-on (SSO). With SSO, users that sign in to one application by means of, for example, their Windows Live® ID credentials are able to visit other sites that use Windows Live ID without being prompted to reenter their credentials.

Alternatively, applications may need to authenticate users with accounts defined within the corporate domain; or support a combination of federated and corporate credentials, and allow users to choose which they specify to sign in. In addition, when using Service Bus in the Azure™ technology platform, access to Service Bus Relay, queue, and topic endpoints must be secured by requiring a token containing the appropriate claims to be presented.

Hh868049.note(en-us,PandP.10).gifBharath Says:
Bharath Federated claims-based authentication and single sign-on are powerful techniques that can simplify development as well as providing benefits to users by making it easier to access different applications without requiring them to reenter their credentials every time.

All of these scenarios can be implemented using claims-based authentication, where a Security Token Service (STS) generates tokens that are stored in cookies in the user's web browser or presented by services when they make a request to a server. This appendix describes the Windows technologies that are available to help you implement claims-based authentication, federated authentication, single sign-on, and security for Service Bus queues.


This appendix does not provide a full reference to claims-based authentication technologies and techniques. A detailed exploration of claims-based authentication, authorization, and Azure Access Control Service can be found at "Claims-Based Identity and Access Control Guide" available at <A class=uri href="">

Uses Cases and Challenges

Most business applications require that users are authenticated and authorized to perform the operations provided by the application. The following sections describe the most common generic use cases for authentication and authorization. The solutions you implement must be reliable, responsive, available, and secure. They must be able to uniquely and accurately identify users and provide information that the application can use to decide what actions that user can take. The solutions should also be as unobtrusive as possible so that the task of signing in is simple and painless.

Hh868049.note(en-us,PandP.10).gifPoe Says:
Poe Poorly designed or badly implemented authentication can be a performance bottleneck in applications. Users expect authentication to be simple and quick; it should not get in the way of using the application.

Authenticating Public Users

Publicly available applications, such as online shopping sites or forums, typically need to authenticate a large number of users, of whom the application has no prior knowledge. Users register by providing information that the site requires, such as a name and address, but the key factor is to be able to uniquely identify each user so that the correct information can be mapped to them as they sign on next time.

Applications may store the users' credentials and prompt for users to enter these when signing on. However, for public applications, it is useful to allow users to sign in with credentials that they use for other websites and applications so that they do not need to remember another user name and password. By using federated authentication, an application can delegate the responsibility for this task to an external identity provider that handles storing the credentials and checking them when the user signs in. This approach also removes the responsibility for storing sensitive credentials from your application, as this is now the responsibility of the identity provider.


The section "Federated Authentication" later in this appendix provides more details of how this works.

Authenticating Corporate Users and Users from Partner Organizations

Applications used by only a limited and known set of users generally have different requirements than public applications. Users are not usually expected to register before using their account; they expect the organization to already have an account configured for them. In addition, the account details will often be more comprehensive than those held by a public application or social identity provider, and not editable by the user. For example, the account will typically define the membership of security groups and the users' corporate email addresses.

This approach is generally used for "internal" or corporate accounts in most organizations, and is exposed to applications though the built-in operating system features and a directory service. However, where known users from partner organizations must be able to authenticate, an intermediary service that is available outside of the organization is required to generate the claims-based identity tokens. This can be achieved using the same federated authentication techniques as described later in this appendix.

Authorizing User Actions

Identifying individual users is only part of the process. After authentication, the application must be able to control the actions users can take. With claims-based authentication, the token the user obtained from their chosen identity provider may contain claims that specify the role or permissions for the user.

However, this is generally only the case when the user was authenticated by a trusted identity provider that is an enterprise directory service, and consequently contains role information for each user (such as "Manager" or "Accounting"). Social identity providers such as Windows Live ID and Google typically include only a claim that is the unique user identifier, and perhaps the name, so in this case you must implement a mechanism that matches the user identifier with data held by your application or located in a central user repository.

This repository must contain the roles, permissions, or rights information for each user that the application can use to authorize the users' actions. In the case of a public application such as a shopping website the repository will typically hold the information provided by users when they register, such as address and payment details, allowing you to match users with their stored account details when they sign in.

Hh868049.note(en-us,PandP.10).gifJana Says:
Jana Claims-based and federated identity solutions allow you to clearly separate the tasks of authentication and authorization, so that changes to one of these do not impact the other. This decoupling makes it easier to maintain and update applications to meet new requirements.

Authorizing Service Access for Non-Browser Clients

Claims-based identity techniques work well in web browsers because the automatic redirection capabilities of the browser make the process seamless and automatic from the user's point of view. For non-browser clients, such as other applications that make service requests to your application's web services, you must publish information that allows the client to discover how to obtain the required token, the accepted formats, and the claims that the token must contain.

The client is responsible for obtaining the required token from a suitable identity provider and STS, and presenting this token with the request. After the application receives the token, it can use the claims it contains to authorize access. If the token contains only a unique identifier, the application may need to map this to an existing account to discover the roles applicable to that client.

Authorizing Access to Service Bus Queues

Hybrid applications that use Azure Service Bus queues must be able to authenticate users, client applications, and partner applications that access the queues. Clients accessing a Service Bus queue can have one of three permission levels: Send, Listen, or Manage. It is vital for security reasons that clients connecting to a queue have the appropriate permissions to prevent reading messages that should not be available to them, or sending messages that may not be valid.

Hh868049.note(en-us,PandP.10).gifMarkus Says:
Markus Service Bus topics and subscriptions behave in the same way as queues from a security perspective, and you authenticate users and authorize access to operations in the same way.

Authorizing Access to Service Bus Relay Endpoints

Hybrid applications that use Azure Service Bus Relay must be able to authenticate users, client applications, and partner applications that access Service Bus Relay endpoints. Clients accessing a Service Bus Relay endpoint must present a suitable token unless the endpoint is configured to allow anonymous (unauthenticated) access. The service is likely to be inside the corporate network or a protected boundary, so is vital for security reasons that clients accessing it through Service Bus Relay have the appropriate permissions in order to prevent invalid access.

Service Bus integrates with Azure Access Control Service, which acts as the default identity provider for Service Bus queues and Service Bus Relay endpoints. However, you can configure Service Bus to use other identity providers if you wish.

Cross-Cutting Concerns

Authentication and authorization mechanisms must, by definition, be secure and robust to protect applications from invalid access and illegal operations. However, other requirements are also important when considering how to implement authentication and authorization in Azure hybrid applications.


The identity of a user or client must be established in a way that uniquely identifies the user with a sufficiently high level of confidence, and is not open to spoofing or other types of attack that may compromise the accuracy of the result. When using federated authentication and delegating responsibility for validating user identity, you must be able to trust the identity provider and any intermediate services with the appropriate level of confidence.

Access to STSs and identity providers should take place over a secure connection protected by Secure Sockets Layer (SSL) or Transport Layer Security (TLS) to counter man-in-the-middle attacks and prevent access to the credentials or authentication tokens while passing over the network.

Many STSs can encrypt the authentication tokens they return, and this should be considered as an additional layer of protection, even when using secure connections.

If an in-house repository of user information is maintained, this must be protected from external penetration through unauthorized access over the network, and from internal attack achieved by means of physical access to the servers, by setting appropriate permissions on the repository tables and content. All sensitive information should be encrypted so that it is of no use if security is compromised.

You must be aware of legal and contractual obligations with regard to personally identifiable information (PII) about users that is held in the repository.


Authentication mechanisms can be a bottleneck in applications that have many users signing in at the same time, such as the start of a working day. The implementation you choose must be able to satisfy requests quickly during high demand periods. Keep in mind that the process can involve several network transitions between identity providers and STSs, and any one of these may be a weak point in the chain of events.


Authentication mechanisms are often a single point of failure. While it is easy to add more servers to an application to handle additional capacity, this approach is often more difficult with authentication mechanisms that must all access a single repository, or use an external identity provider over which you have no control. If the authentication mechanism fails, users will not be able to access the application.


The protocols and mechanisms for claims-based authentication are interoperable by default. They use standards-based protocols and formats for communication and security tokens. However, some STSs and identity providers may only provide one type of token, such as a Simple Web Token (SWT), whereas others might accept or return other types such as Security Assertions Markup Language (SAML) tokens. You must ensure that the external providers and services you choose are compatible with requirements and with each other.

Claims-Based Authentication and Authorization Technologies

This section provides a brief overview of the technologies for authentication and authorization that are typically used in Windows applications and applications hosted in Azure. It focuses on claims-based authentication, which is likely to be the most appropriate approach for hybrid applications. It covers:

  • Federated authentication, security token services, and identity providers
  • Windows Identity Foundation (WIF)
  • Azure Access Control Service (ACS)

Federated Authentication

In traditional applications, authentication and authorization are typically operating system features that make use of enterprise directory services such as Microsoft Active Directory® and resource permissions settings such as Access Control Lists (ACLs). More recently, frameworks and technologies such as Microsoft ASP.NET have provided built in mechanisms that implement a similar approach for web-based applications.

However, all of these approaches require the maintenance of a user directory that defines which users can access the application or service, and what these users can do within the application or service. Maintaining such lists is cumbersome and can even be prone to errors or lack of security. For example, if you store the list of users in a partner organization that can access your application, you depend on that partner to tell you when a user leaves the company or when the permissions required by specific users change.

Instead, you can choose to trust the partner and allow that partner to maintain the list of users and their roles. You still retain control of authorization so you can manage what users can do within the application, but you are freed from the need to authenticate every user and allocate them to the appropriate authorization roles or groups.

This approach to delegated authentication requires a standard way of querying user repositories and distributing tokens that contain claims. Security Token Services (STSs) such as Microsoft Active Directory Federation Service (ADFS) and Azure Access Control Service provide this capability, and compatible STSs are available for other platforms and operating systems.

Each STS uses Identity Providers (IdPs) that are responsible for authenticating users. After the identity provider authenticates the user, the STS will create a token containing the claims for this user. When using a web browser, this token is delivered in a cookie; for smart clients and service applications the token is delivered within the service response (depending on the protocol in use). An STS may also deliver a cookie to the web browser that indicates the user has been authenticated, allowing this user to access other applications without needing to reenter credentials. This provides a single sign-in (SSO) experience.

Hh868049.note(en-us,PandP.10).gifBharath Says:
Bharath ADFS is an IdP as well as an STS because it can use Active Directory to validate a user based on credentials the user provides. ACS uses external IdPs such as Windows Live ID, Google, Facebook, and OpenID, but you can also define service identities in ACS that allow clients to authenticate without using an external IdP.

In practice, you decide which STS your application will trust. This may be an STS that you own, such as ADFS connected to your corporate Active Directory. Alternatively, it may be an external STS such as ACS. You can also configure an STS to trust another STS, so that users can be authenticated by any of the STSs in the trust chain, as shown in Figure 1.


Figure 1

An authentication trust chain that can support federated identity and single sign-on

An Overview of the Claims-Based Authentication Process

An STS chooses an IdP that will authenticate the user based on the user's home realm or domain. For example, a user has a home realm of Google if this user has an identity that is managed and authenticated by Google. If a user's account is in a company's Active Directory, their home realm will be that company's corporate domain. For users authenticating through a web browser, the STS directs the user to the appropriate IdP. If the user can be successfully authenticated, the IdP returns a token containing claims (information) about that user to the STS. The STS then generates an application-specific token, which can contain these claims or some augmented version of the claims, and redirects the user to the application with this token. The application can use the claims in this token to authorize user actions. Figure 2 shows a simplified view of the process when using ACS as the token issuer.


Figure 2

A simplified view of the browser authentication process using ACS and social Identity providers

To support single sign-on, the STS can store an additional cookie containing an STS-specific token in the browser to indicate that the user was successfully authenticated. When the user accesses another application that trusts the same STS, this STS can generate a suitable token without requiring the user to authenticate again with the original IdP.

Authorizing Web Service Requests

The automatic redirection process described above is only applicable when authenticating requests that come from a web browser. Requests to a web service may be generated by code running in another application, such as a smart client application or service application. In an environment such as this, outside of a web browser, request redirection and cookies cannot be used to direct the request along the chain of STSs and IdPs.

When using claims authentication with a smart client application or a web service, the client must actively request the tokens it requires at each stage, and send these tokens along with the request to the next party in the authentication chain. Figure 3 shows a simplified view of the process for a smart client or service application when using ACS as the token issuer.


Figure 3

A simplified view of the smart client or service authentication process using ACS and social Identity providers

Claims-based authentication for web browsers is known as passive authentication because the browser automatically handles the redirection and presentation of tokens at the appropriate points in the authentication chain of events. Authentication for service calls, where this process must be specifically managed by the application code, is referred to as active authentication. For more information about active authentication, see "Claims Enabling Web Services."

Windows Identity Foundation

Microsoft provides a framework that makes it easy to implement claims-based authentication and authorization in web applications and service applications. Windows Identity Foundation (WIF) is a core part of the Microsoft identity and access management framework based on Active Directory, Active Directory Federation Services, Azure Access Control Services, and federated claims-based authentication.

WIF automatically checks requests for the presence of the required claims tokens, and performs redirection for web browsers to the specified STS where these can be obtained. It also exposes the claims in valid tokens to application code, so that the code can make authorization decisions based on these claims. WIF includes a wizard that developers can use in the Visual Studio® development system, or from the command line, to configure applications for claims-based identity.

The WIF components expose events as they handle requests, allowing developers to control the process as required. WIF also includes controls that can be embedded in the application UI to initiate sign-in and sign-out functions.


For more information about Windows Identity Foundation, see the Identity Management home page and the patterns & practices "Claims Based Identity & Access Control Guide" at <A class=uri href="">

Azure Access Control Service

Azure Access Control Service (ACS) is a cloud-based service that makes it easy to authenticate and authorize website, application, and service users and is compatible with popular programming and runtime environments. ACS integrates with the WIF tools and environments and Microsoft Active Directory Federation Services (ADFS), and supports a range of protocols that includes OAuth, OpenID, WS-Federation, and WS-Trust. It allows authentication to take place against many popular web and enterprise identity providers.

When a user requests authentication from a web browser, ACS receives a request for authentication from the web application and presents a home realm discovery page that lists the identity providers the web application trusts. 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. The rules configured within ACS can perform protocol transition and claims transformation as required by the web application. It then redirects the user back to the web application with the ACS token. The web application can use the claims in this token to apply authorization rules appropriate for this user.

ACS accepts SAML 1.1, SAML 2.0, and SWT formatted tokens, and can issue a SAML 1.1, SAML 2.0, or SWT token.

The process for authentication of requests from smart clients and other service applications 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.

ACS also acts as a token issuer for Azure Service Bus. You can configure roles and permissions for Service Bus queues and Service Bus Relay endpoints within ACS. Service Bus automatically integrates with ACS and uses it to validate access and operations on queues and endpoints.

ACS is configured through the service interface using an OData-based management API, or through the web portal that provides a graphical and interactive administration experience. You can also use Azure PowerShell® command-line interface cmdlets to configure ACS. These cmdlets provide wrappers around the OData API and enable you to write scripts that you can use to help automate many ACS configuration tasks.


For more information about the Azure PowerShell cmdlets visit the Azure PowerShell page.

ACS and Unique User IDs

One point to be aware of if you decide to use ACS is that the user ID it returns after authenticating a user is unique not only to the user, but also to the combination of ACS instance and user. Each configured instance of an ACS namespace generates a different user ID for the same user. If a user is authenticated through Windows Live ID in one ACS instance, the ID it returns will be different from the ID returned when the same user was authenticated by Windows Live ID through a different ACS instance. This is done to protect user privacy; it prevents different applications from identifying users through their ID when they are authenticated by different ACS instances.

If you deploy multiple instances of ACS in different datacenters or change the namespace of your ACS instance you must implement a mechanism that matches multiple ACS-delivered unique IDs to each user in your user data store.


For more information about Azure Access Control Service, see "Access Control Service 2.0" and the patterns & practices "Claims Based Identity & Access Control Guide" at <A class=uri href="">

Azure Service Bus Authentication and Authorization

Azure Service Bus is a technology that allows you to expose internal services through a corporate firewall or router without having to open inbound ports or perform address mapping. It creates a virtual endpoint in the cloud that users connect to, and the requests and messages are passed to your service or message queue. "Appendix C - Implementing Cross-Boundary Communication" covers Service Bus in more detail; in this section you will see how the integration with ACS is used to authenticate Service Bus requests.

Service Bus integrates with ACS for authenticating requests. For every Service Bus namespace created in the Azure Management Portal there is a matching ACS namespace, created automatically, which is used to authenticate Service Bus requests. This ACS namespace is the Service Bus namespace with the suffix "-sb". It has the Service Bus namespace as its realm, and generates SWTs with an expiration time of 1200 seconds. You cannot change these settings for the default internal identity provider, but you can add additional identity providers that have different behavior. You can also configure access rules and rule groups for your services within this ACS namespace.

Hh868049.note(en-us,PandP.10).gifMarkus Says:
Markus To view and configure the settings and rules for an ACS namespace that authenticates Service Bus requests, navigate to the Service Bus namespace in the Azure portal and click the "Access Control" icon at the top of the window. You can also configure the ACS namespace programmatically using the Management API.

Client Authentication

Figure 4 shows the overall flow of requests for authenticating a client and accessing an on-premises service through Service Bus. Clients accessing Service Bus Relay endpoints or Service Bus queues must obtain a token from ACS that contains claims defining the client's roles or permissions (1 and 2), and present this token to Service Bus (3) along with the request for the service or access to a message queue. Service Bus validates the token and allows the request to pass to the required service (4). The only exception is if you specifically configure a Service Bus Relay endpoint to all allow unauthenticated access. You cannot configure unauthenticated access for Service Bus queues.


Figure 4

Authenticating a Service Bus request with ACS

To allow unauthenticated access to a Service Bus Relay endpoint you set the RelayClientAuthenticationType property of the WCF relay binding security element to None. For more information, see "Securing Services" in the MSDN WCF documentation and "Securing and Authenticating a Service Bus Connection."

The token issued by ACS can contain multiple claims. For example, when using Service Bus queues the token may contain claims that allow the client to send messages to a queue, listen on a queue, and manage a queue. When using Service Bus Relay, the claims can allow a client to register an endpoint to listen for requests, send requests to a service, and manage the endpoint. However, it is possible that the service itself (in Figure 4, the internal on-premises service) will require additional credentials not related to Service Bus. The ACS token simply allows access to the service through Service Bus; other authentication and message security issues are the same as when calling a service directly. For example, you may need to provide separate credentials within the service call headers that allow the client to access specific resources within the server that is hosting the service.

Hh868049.note(en-us,PandP.10).gifJana Says:
Jana The authentication process for accessing a Service Bus Relay endpoint is entirely separate from any other authentication and security concern related to calling the service itself. Service Bus Relay simply provides a routing mechanism that can expose internal services in a secure way; the techniques you use to protect and secure the service itself and the resources it uses are no different from when you expose it directly over a network.

ACS is an STS that can be configured to trust other identity providers. This is useful where you want to be able to authenticate clients in a specific domain, such as your own corporate domain, to manage access to internal services exposed through Service Bus. For example, you may expose a service that external employees and partners use to submit expenses. Each valid user will have an existing account in your corporate directory.

Figure 5 shows this approach. A client first obtains a token from the corporate ADFS and Active Directory service (1 and 2), then presents this token to ACS (3). ACS is configured to trust the ADFS instance as an identity provider. ACS validates the token presented by the user with ADFS, and exchanges it for an ACS token containing the appropriate claims based on transformations performed by ACS rules (4). The client can then present the ACS token with the service request to Service Bus (5). Service Bus validates the token and allows the request to pass to the required service (6).


Figure 5

Authenticating a Service Bus request with ADFS and ACS

A similar approach can be taken with other identity providers that can generate SAML tokens. The ACS namespace used by Service Bus can also be configured with several identity providers, allowing clients to choose which one to use.

Service Bus Tokens and Token Providers

Unless the endpoint is configured for unauthenticated access, clients must provide a token to ACS when accessing Service Bus endpoints and queues. This token can be one of the following types:

  • Shared secret. In this approach, the client presents a token containing the service identity and the associated key to ACS to obtain an ACS token to send with the request to Service Bus. The service identity is configured in the ACS Service Bus namespace, which can generate a suitable key that the client will use. This is the approach shown in Figure 4 earlier in this appendix.
  • Simple Web Token (SWT). In this approach, the client obtains an SWT from an identity provider and presents this to ACS to obtain an ACS token to send with the request to Service Bus. Figure 5 earlier in this appendix shows the overall process for this approach.
  • SAML Token. In this approach, the client obtains a SAML token from an identity provider and presents this to ACS to obtain an ACS token to send with the request to Service Bus. Figure 5 earlier in this appendix also shows the overall process for this approach.

To include the required token with a request, the client uses the Service Bus MessagingFactory, NamespaceManager, or TransportClientEndpointBehavior class. All of these types contain methods that accept an instance of a concrete class that inherits the abstract TokenProvider base class, such as SamlTokenProvider, SharedSecretTokenProvider, and SimpleWebTokenProvider.

The concrete TokenProvider implementations contain methods that create the corresponding type of token from string values and byte arrays, or from existing tokens. You can create custom implementations of TokenProvider to perform other approaches to token creation; perhaps to implement a federated authentication mechanism if this is required.


For more information, see "TokenProvider Class" on MSDN.

Service Bus Endpoints and Relying Parties

ACS automatically generates a default relying party in the corresponding ACS namespace when you configure a namespace in Service Bus. This relying party has a realm value that encompasses all endpoint addresses you define within the namespace. It is effectively the root of your Service Bus namespace.

However, you can define additional relying parties within the ACS namespace that correspond to endpoint addresses you add to the Service Bus namespace. For example, if your root namespace in Service Bus is treyresearch, you might define additional endpoints such as the following:

You can create multiple relying party definitions in ACS that correspond to any subsection of the endpoints defined in Service Bus. ACS matches a request with the longest matching definition, and applies the permissions specified for that definition. This allows you to set up granular control of permissions to each endpoint, or to groups of endpoints. For example, from the list of shown above, the definition for would be used for requests to because there is no more specific match available.

Authorization Rules and Rule Groups

The ACS Service Bus namespace contains rules and rule groups that specify the roles and permissions for clients based on their authenticated identity. ACS automatically creates a default rule that provides Send, Listen, and Manage permissions to the service owner and the root relying party definition. The default owner identity should be used only for administrative tasks. You should create additional service identities within ACS for clients, and assign the appropriate permissions (Send, Listen, and Manage) to each one to restrict access to the minimum required.

For each relying party definition you specify rules that transform the claims in the token received by ACS, and/or rules that add claims. When using the shared secret approach for authentication, there is no existing token and so there are no existing input claims. The output claims are of the type, and have the values Send, Listen, and Manage. You can add more than one claim to any rule. To make configuration easier, you can create rule groups and apply these to multiple relying parties.


For a comprehensive list of tutorials on using ACS, including configuring identities and identity providers, see "ACS How Tos" on MSDN. For a step-by-step guide to configuring rules and rule groups, see "How To Implement Token Transformation Logic Using Rules" on MSDN.

More Information

All links in this book are accessible from the book's online bibliography available at:

Next Topic | Previous Topic | Home

Last built: June 4, 2012