How to: Request a Token from ACS via the OAuth WRAP Protocol

Applies To

• Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS)

Overview

When your web applications and services handle authentication using ACS, the client must obtain a security token issued by ACS to log in to your application or service. In order to obtain this ACS-issued token (output token), the client must either authenticate directly with ACS or send ACS a security token issued by its identity provider (input token). ACS validates this input security token, processes the identity claims in this token through the ACS rules engine, calculates the output identity claims, and issues an output security token.

This topic describes the methods of requesting a token from ACS via the OAuth WRAP protocol. All token requests via the OAuth WRAP protocol are transmitted over SSL. ACS always issues a Simple Web Token (SWT) via the OAuth WRAP protocol, in response to a correctly formatted token request. All token requests via the OAuth WRAP protocol are sent to ACS in an HTTP POST. You can request an ACS token via the OAuth WRAP protocol from any platform that can make an HTTPS FORM POST: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash, and other platforms.

The following table lists three supported methods of requesting an ACS-issued SWT token via the OAuth WRAP protocol.

Three methods of requesting a token from ACS via the OAuth WRAP protocol

Token issuing endpoint

All ACS token requests via the OAuth WRAP protocol are directed at an ACS token-issuing endpoint. The URI of this endpoint depends on the Access Control namespace. The namespace appears as a DNS name prefix in a token request URI. The rest of the DNS name is fixed, as is the path. For example, if you want to request a token from the Access Control namespace called "mysnservice", you can direct a token request to the following URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Password token requests

With a password token request, a client can send a user name and password from a service identity directly to ACS via the OAuth WRAP protocol for authentication. This is the easiest way to request a token from ACS using the OAuth WRAP protocol. Other than establishing an SSL connection, this approach requires no cryptographic capability. In practice, it is similar to the username/password model that is prevalent in REST Web services. This type of token request is actually an HTTPS form POST. The parameters in a password token request are form-encoded.

The following is an example of a wire trace of a plaintext request to a namespace called “mysnservice”.

POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_name=mysncustomer1&
wrap_password=5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ%3D

The table below provides the names, descriptions, and value requirements of the parameters that are required to be present in a password token request:

The values of these parameters must be URL-encoded before you send the request to ACS. Your web application or service can provide the value of the wrap_scope to the client, or the client can decide to set the value of the wrap_scope parameter to the URI of the web application or service resource target.

Password token requests via the OAuth WRAP protocol can also contain additional parameters which ACS can use during the output claim calculation process. These additional parameter names and values must be URL-encoded and values must not be quoted.

The password token request method is fairly straightforward using .

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");

// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

For information on how to unpack the output token from ACS and send it to the web application or service, see Unwrapping and sending the token to a web application or service.

SWT token requests

You can also request a token from ACS via the OAuth WRAP protocol using a SWT token signed by a symmetric key. All SWT token requests are made through an HTTPS form POST. The parameter values in this token request method are form-encoded.

The following is an example of a wire trace of a SWT token request to the "mysnservice" namespace.

POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_assertion_format=SWT&
wrap_assertion=Issuer%3dmysncustomer1%26HMACSHA256%3db%252f%252bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%253d

A SWT token request must have the following parameters and values:

As shown in the following example, the code that is required to make a SWT token request resembles the code that is required to make a password token request.

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
// add the wrap_scope
values.Add("wrap_scope", "http://mysnservice.com/services");
// add the format
values.Add("wrap_assertion_format", "SWT");
// add the SWT
values.Add("wrap_assertion", "Issuer=mysncustomer1&HMACSHA256=b%2f%2bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%3d");
// WebClient takes care of the remaining URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

For information on how to unpack the response from ACS and send it to your web application or service, see Unwrapping and sending the token to a web application or service.

Creating a SWT token

A SWT token is a set of key/value pairs that are signed with an issuer key (a symmetric key). A SWT token sent to ACS in a SWT token request, must contain the Issuer and HMACSHA256 parameters, as well as additional parameters, for example, ExpiresOn, Audience, and other client-specific claims. The following table provides the names and descriptions of SWT token parameters:

The following code sample shows how to generate an SWT token using . It contains a type that builds SWT tokens that contain the Issuer and HMACSHA256 parameters.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Web;

public class TokenFactory
{
    string signingKey;   
    string issuer;
    
    public TokenFactory(string issuer, string signingKey)
    {
        this.issuer = issuer;
        this.signingKey = signingKey;
    }

    public string CreateToken()
    {
        StringBuilder builder = new StringBuilder();

        // add the issuer name
        builder.Append("Issuer=");
        builder.Append(HttpUtility.UrlEncode(this.issuer));

        string signature = this.GenerateSignature(builder.ToString(), this.signingKey);
        builder.Append("&HMACSHA256=");
        builder.Append(signature);

        return builder.ToString();
    }

   
    private string GenerateSignature(string unsignedToken, string signingKey)
    {
        HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(signingKey));

        byte[] locallyGeneratedSignatureInBytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(unsignedToken));

        string locallyGeneratedSignature = HttpUtility.UrlEncode(Convert.ToBase64String(locallyGeneratedSignatureInBytes));

        return locallyGeneratedSignature;
    }
}

SAML token requests

The SAML token request method is intended mainly for the AD FS 2.0 integration and allows the client to use an enterprise identity (Active Directory) to authenticate with ACS. With the SAML token request method, you can send a signed SAML 1.1 or a SAML 2.0 token issued by AD FS 2.0 (input token) to ACS via the OAuth WRAP protocol.

ACS uses its rules to calculate the output claims, groups them into a SWT token (output token), signs it, and returns it to the client via the OAuth WRAP protocol.

A SAML token request must have the following parameters and values:

The following is an example of the code that is required to make a SAML token request.

private static string SendSAMLTokenToACS(string samlToken)
{
 try
 {
  WebClient client = new WebClient();
  client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
  NameValueCollection parameters = new NameValueCollection();
  parameters.Add("wrap_assertion_format", "SAML");
  parameters.Add("wrap_assertion", samlToken);
  parameters.Add("wrap_scope", "http://mysnservice.com/services");

  byte[] responseBytes = client.UploadValues("WRAPv0.9", parameters);
  string response = Encoding.UTF8.GetString(responseBytes);

  return response
   .Split('&')
   .Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
   .Split('=')[1];
 }
 catch (WebException wex)
 {
  string value = new StreamReader(wex.Response.GetResponseStream()).ReadToEnd();
  throw;
 }
}  

For information on how to unpack the response from ACS and send it to your web application or service, see Unwrapping and sending the token to a web application or service.

Claims assertion via the OAuth WRAP protocol

To enable backwards compatibility with ACS 1.0 token request behavior, ACS supports the ability to assert claims as part of token requests.

Register the asserting application or service as an ACS identity provider.

The recommended way to do this is to register the asserting application or service as an ACS identity provider. Then the application or service requests a token from ACS by presenting a SAML or SWT token that contains the claims that it wants to assert, and this token is signed using an Identity Provider Key stored in ACS. For example, you can send a SAML token request with asserted claims to ACS via the OAuth WRAP protocol from AD FS 2.0 or any custom Security Token Service (STS) that is built using Windows Identity Foundation (WIF) and registered in ACS as a WS-Federation identity provider.

You can use the ACS Management Portal to register an identity provider using WS-Federation metadata, or you can use the ACS Management Service to individually set identity provider properties, addresses, and keys. (For example, see How to: Use ACS Management Service to Configure AD FS 2.0 as an Enterprise Identity Provider.) No service identities are required in this method of asserting claims in a token request. This method is functional via all ACS-supported protocols.

Unwrapping and sending the token to a web application or service

If the token request is successfully authenticated, ACS returns two form-encoded parameters: wrap_token and wrap_token_expires_in. The values of these parameters are the actual SWT token that the client can use to gain access to your web application or service and the approximate remaining lifetime of this token (in seconds), respectively.

Before sending the SWT token to the web application or service, the client must extract and URL-decode it from the ACS response. If the web application or service requires the token to be presented in the HTTP Authorization header, the token must be preceded by the scheme WRAPv0.9.

The following code example demonstrates how to unpack a token and format the Authorization header.

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");

// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

string token = response
    .Split('&')
    .Single(value => value.StartsWith("wrap_token=", StringComparison.OrdinalIgnoreCase))
    .Split('=')[1];

string.Format("WRAP access_token=\"{0}\"", HttpUtility.UrlDecode(token));

ACS Error Codes and Descriptions

ACS returns errors when it cannot satisfy a token request. In keeping with the REST design, the error contains an HTTP response code. In many cases, ACS errors also contain a SubCode and Detail that provide context about what failed. The error format is: Error:Code:<httpStatus>:Sub-Code:<code>:Detail:<message>. The Content-Type of an error is always text/plain.

HTTP/1.1 401 Access Forbidden
Content-Type: text/plain; charset=us-ascii

Error:Code:401:SubCode:T0:Detail:ACS50009: SWT token is invalid. :TraceID:<trace id value>:TimeStamp:<timestamp value>

For more information on ACS error codes, see ACS Error Codes.

When debugging or recovering from an error returned from ACS, it is often required to read the response body. The following code example shows how to read the error message from a WebException object.

try
{
    WebClient client = new WebClient();
    client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

    NameValueCollection values = new NameValueCollection();
    values.Add("wrap_name", "mysncustomer1");
    values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
    values.Add("wrap_scope", "http://mysnservice.com/services");

    // WebClient takes care of the URL Encoding
    byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

    // the raw response from ACS
    string response = Encoding.UTF8.GetString(responseBytes);

    string token = response
        .Split('&')
        .Single(value => value.StartsWith("wrap_access_token=",       StringComparison.OrdinalIgnoreCase))
        .Split('=')[1];
}
catch (WebException wex)
{
    if (wex.Response != null)
    {
        // the response Stream contains the error message
        StreamReader reader = new StreamReader(wex.Response.GetResponseStream());
        string message = reader.ReadToEnd();
    }
    // Throw as appropriate
}

See Also

Concepts

ACS How To's