Share via


Token Formats Supported in ACS

Updated: June 19, 2015

Applies To: Azure

When your web applications and services handle authentication with Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS), the client must obtain a security token issued by ACS to log in to your application or service. ACS can issue security tokens in the following formats:

  • Security Assertion Markup Language (SAML) 1.1 and 2.0

  • Simple Web Token (SWT)

  • JSON Web token (JWT)

Note

ACS can issue security tokens in any of the following formats. The token format that ACS uses for a web application or service is determined by the relying party application configuration. For information about configuring relying party applications, see Relying Party Applications.

Security Assertion Markup Language (SAML) 1.1 and 2.0

Security Assertion Markup Language (SAML) is the oldest and the most common format of tokens in use today for single sign-on (SSO) and claims-based identity. SAML specifies an XML format, for tokens as well as protocols, for performing a web application or a web service SSO using SAML tokens. For more information about SAML tokens, see SAML Specifications (https://go.microsoft.com/fwlink/?LinkID=213719).

Note

SAML 1.1 and SAML 2.0 tokens are widely supported by a number of development platforms, including Windows Identity Foundation (https://go.microsoft.com/fwlink/?LinkID=213729).

The following is an example of a SAML token.

<assertion id="_4fe09cda-cad9-49dd-b493-93494e1ae4f9" issueinstant="2012-09-18T20:42:11.626Z"
    version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
<issuer>https://test05.accesscontrol.windows.net/</issuer>
<ds:signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:signedinfo>
        <ds:canonicalizationmethod algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        <ds:signaturemethod algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
        <ds:reference uri="#_4fe09cda-cad9-49dd-b493-93494e1ae4f9">
            <ds:transforms>
                <ds:transform algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                <ds:transform algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            </ds:transforms>
            <ds:digestmethod algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
            <ds:digestvalue>8qmfRKuATFuo4M96xuci7HCLUGUeO3eBxHOi9/HaFNU=</ds:digestvalue>
        </ds:reference>
    </ds:signedinfo>
<ds:signaturevalue>UWcXJElfrP8hfdNi8ipzSjfxCYGYzoylkn5HdSa8IhphvyZBvbZl1OFEbMSygoo8xNgnywUNPuzZP8nV7CwZNuSWVZZSrF2pHAswBKQoJoodpzrGRR0ruT+A2sjXfnLQqN+X/xanXqqg4ViUOR9xHvn8vzaRwYxPPsjI4OXq0hzLlyuBzhw42XHzZk1qknQr1wp/lZTMwrFnY38gziUZ+Ci1Duen5Xt9k+0ZFujtSBqJKIran1V263o8CkvoahNcNKT//OcXc3va7zeJf67V9/lwY34MkFoqqfeuTSzEuZfk7pYRNqwhOZGhokpR+1qHjEbJr3p6dOOPkuQp9p6zsQ==</ds:signaturevalue>
    <keyinfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data>       <X509Certificate>MIIDCDCCAfCgAwIBAgIQRmI8p7P/aphMv5Kr9vQpqTANBgkqhkiG9w0BAQUFADAtMSswKQYDVQQDEyJBQVJPTkJPT0subnRkZXYuY29ycC5taWNyb3NvZnQuY29tMB4XDTEyMDUyMTIzMjMxMFoXDTEzMDUyMTAwMDAwMFowLTErMCkGA1UEAxMiQUFST05CT09LLm50ZGV2LmNvcnAubWljcm9zb2Z0LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAI79l6EOSWswJn3d9i4yfZh9Cwo2XNhb4tOWvmljCKFlrWoz/Drch5aOzdmI/yFaqkyX7BXc/zoSmX1n3VkqHIeJkGECcZX2bD4jPuICVmKBcXo0SeQ+2vF6DoqjVKaegWrPsqmDrlCscnlMLb11Fg1Ffqkm8wyyWwbQvC5VnVf0i9DPE0n+i3NJi9cT57obrNRkQzwfBZy08I2JlpxLfaUUDhHlF99C1MtBduzn3au+S20gom1cHAcSvHBormXbjPZ5F6RJUz7kO/U+M5rYkiS+vtANtnBlUAK8fRmEUrYFRMr1tyiOXcRid/7UJP3e0EmAsneMnuD9WO/mK6MuzIECAwEAAaMkMCIwCwYDVR0PBAQDAgQwMBMGA1UdJQQMMAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBBQUAA4IBAQBCRM9maY5ZE+wIxefxjT0IAqp7H6l062PKOGdld5MapOJUWbng2CrfUV3YI5OSD9yhevgDne3jf2DUBv5QndHdms+FL260ydDmwet4A5kJi3ZBO4sR/PZTz3FdeeOwdTeUS2wAMJuphAZ1+PUVk25bbEu/DKmgeYzRn64CHWqk5sPKzH9jAszvX2EeoClI+8Sp/bXHTwzEUOFYcicPOO+tuFTqHOYBDT5bE42rAp/SaC1wXbmTCGS12gfCZCrlml6LZNTsKQWBF2szXOPGcFcInGkauZDUUtZd+921uy0E/sYwgNfi8phU1aGZjIESVFQ70LpfvIMwF6++BRX12icW</X509Certificate>
        </X509Data>
    </keyinfo>
</ds:signature>
<subject>
    <NameID>abc1def2ghi3jkl4mno5pqr6stu7vwx8yza9bcd0efg=</NameID>
    <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />
</subject>
    <conditions notbefore="2012-09-18T20:42:11.610Z" notonorafter="2012-09-18T21:42:11.610Z">
        <AudienceRestriction>
            <Audience>https://localhost:63000/</Audience>
        </AudienceRestriction>
    </conditions>
    <attributestatement>
        <Attribute Name="https://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider">
            <AttributeValue>uri:WindowsLiveID</AttributeValue>
        </Attribute>
    </attributestatement>
</assertion>

Simple Web Token (SWT)

Simple Web Token (SWT) tokens comply with the SimpleWebToken specification. SWT tokens are expressed as form-encoded key/value pairs signed with a cryptographic key. The specification mandates the presence of some key/value pairs, but it leaves room for application-specific key/value pairs. The keys that are always present in an ACS-issued SWT token are shown in the following table.

Key Description

Issuer

A representation of the ACS service namespace that issued the token. The pattern for this value is https://<servicenamespace>.accesscontrol.windows.net/.

Audience

The value of the applies_to used to request the token. This value is either an HTTP or HTTPS URI.

ExpiresOn

The Epoch time upon which the token expires.

HMACSHA256

The HMACSHA256 signature of all the other key/value pairs. This key/value pair is always the last key/value pair in the token. The form-encoded representation of the other key/value pairs (including application-specific claims) is signed.

In addition to these key/value pairs, ACS adds one or more claims to a token before issuance. These claims are driven by the rule configuration present in ACS at the time of the token request. All such claims have a type and one or more values, where both the type and the values are strings. When a claim contains more than one value, the values are separated by the comma (“,”) character. Claims are encoded as key/value pairs, exactly as the key/value pairs described in the previous table.

The following is an example of an ACS token that contains claims represented as key/value pairs.

Audience=http%3a%2f%2flocalhost%2fmyservice&ExpiresOn=1255913549Issuer=https%3a%2f%2fmyservice.accesscontrol.windows.net%2f&role=Admin%2cUser&role=Admin%2cUser&&HMACSHA256=sT7Hr9z%2b3t1oDFLpq5GOToVsu6Dyxpq7hHsSAznmwnI%3d

With the exception of the HMACSHA256 key/value pair, these pairs can be in any order. The following ACS token is equivalent to the previous ACS token except for the signatures that are different.

role=Admin%2cUser&customerName=Contoso%20Corporation&Issuer=https%3a%2f%2fmyservice.accesscontrol.windows.net%2f&Audience=http%3a%2f%2flocalhost%2fmyservice&ExpiresOn=1255912922&HMACSHA256=yuVO%2fwc58%2ftYP36%2fDM1mS%2fHr0hswpsGTWwgfvAbpL64%3d

The following table shows the contents of the token with URL decoded values.

Source Key URL encoded value URL decoded value

User-defined Claims

role

Admin%2cUser

Admin,User

customerName

Contoso%20Corporation

Contoso Corporation

System-defined Claims

Issuer

https%3a%2f%2fmyservice.accesscontrol.windows.net%2f

https://myservice.accesscontrol.windows.net/

Audience

http%3a%2f%2flocalhost%2fmyservice

https://localhost/myservice

ExpiresOn

1255912922

1255912922

HMACSHA256

yuVO%2fwc58%2ftYP36%2fDM1mS%2fHr0hswpsGTWwgfvAbpL64%3d

yuVO/wc58/tYP36/DM1mS/Hr0hswpsGTWwgfvAbpL64=

JSON Web token (JWT)

JSON Web token (JWT) support is being added in beta, this means that there can be breaking changes without notice.

The ACS implementation of the JWT token format follows the draft 9 of the JWT specification. For more information, see https://go.microsoft.com/fwlink/?LinkID=253666. Similar to SWT tokens, JWT is a compact token format that is suited for REST web services. Unlike the SWT format, JWT supports a variety of signing options. ACS supports both symmetric and asymmetric signatures for JWT tokens. The claims that are always present in ACS-issued JWT tokens are shown in the following table.

Claim Claim Type used JWT Description

Issuer

iss

A representation of the Access Control namespace that issued the token. The pattern for this value is https://<namespace>.accesscontrol.windows.net/

Audience

aud

The value of the scope used to request the token. This value is used to identify the intended recipient of the token.

Not Before

nbf

The Epoch time before which the token is not valid.

Expiration

exp

The Epoch time upon which the token expires.

The following algorithms are supported for JWT tokens:

Algorithm identifier in JWT header Description

HS256

HMAC using SHA-256 hash algorithm. For signing JWT with a symmetric key .

RS256

RSA using SHA-256 hash algorithm. For signing JWT an asymmetric key, using an x509 with certificate.

Here is an example of a JWT token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwczovL2NvbnRvc28uY29tL3JlbHlpbmdwYXJ0eSIsImlzcyI6Imh0dHBzOi8vY29udG9zby5hY2Nlc3Njb250cm9sLndpbmRvd3MubmV0LyIsIm5iZiI6MTMzNjA2NzMzOCwiZXhwIjoxMzM2MDcwOTM4LCJuYW1laWQiOiJjbGllbnRBcHAiLCJpZGVudGl0eXByb3ZpZGVyIjoiY29udG9zby5jb20ifQ._3dZQ6cmmFgrZ_-VmOLrr7CHne3Xdko_WtE6-Je5Ihw. 

JWT is composed of segments, which are delimited using ‘.’. The following table shows the decoded segments of a JWT token:

JWT Segment Value

JWT Header

{"typ":"JWT","alg":"HS256"}

JWT Claim Set

{"aud":"https://contoso.com/relyingparty","iss":"https://contoso.accesscontrol.windows.net/","nbf":1336067338,"exp":1336070938,"nameid":"clientApp","identityprovider":"contoso.com"}

Signature

_3dZQ6cmmFgrZ_-VmOLrr7CHne3Xdko_WtE6-Je5Ihw

A single claim with multiple values is represented as a JSON array. For example if a user is a member of multiple roles, the role claim would appear as follows:

{
 "aud":"https://contoso.com/relyingparty",
"iss":"https://contoso.accesscontrol.windows.net/",
"nbf":1336067338,"exp":1336070938,
"nameid":"frankm",
"identityprovider":"contoso.com",
“role”: [ “admin”, “user” ]
}

ACS Tokens and Protocols

When a SAML 2.0, SAML 1.1, SWT, JWT token is issued, ACS uses various standard protocols to return the token to a web application or service. ACS supports the following token format/protocol combinations:

  • ACS can issue and return SAML 2.0 tokens over the WS-Trust and WS-Federation protocols (depending on the protocol used in the token request).

  • ACS can issue and return SAML 1.1 tokens over the WS-Federation and the related WS-Trust protocols (depending on the protocol used in the token request).

  • ACS can issue and return SWT tokens over the WS-Federation, WS-Trust, and OAuth WRAP or OAuth 2.0 protocols, (depending on the protocol used in the token request).

  • ACS can issue JWT tokens over the WS-Federation, WS-Trust, and or OAuth 2.0 protocols, (depending on the protocol used in the token request).

See Also

Concepts

ACS Architecture
ACS 2.0 Components