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 |
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).