Share via

Single Sign-on (SAML Protocol)

  • Article

 

Azure Active Directory supports the SAML 2.0 web browser single sign-on (SSO) profile. To request that Azure Active Directory authenticate a user, the cloud service (the service provider) must use an HTTP Redirect binding to pass an AuthnRequest (authentication request) element to Azure Active Directory (the identity provider). Azure Active Directory uses an HTTP Post binding to post a Response element to the cloud service.

This topic describes the SAML 2.0 authentication requests and responses that Azure Active Directory supports for single sign-on. It lists and describes the required, optional, ignored, and unsupported elements and attributes, and value requirements.

This diagram depicts the workflow of the Azure Active Directory authentication process for single sign-on.

Single sign-on workflow diagram

AuthnRequest

This section describes the elements in a SAML 2.0 authorization request to Azure Active Directory. The following is a sample SAML 2.0 AuthnRequest element with only the required attributes.

<samlp:AuthnRequest 
xmlns="urn:oasis:names:tc:SAML:2.0:metadata" 
ID="id6c1c178c166d486687be4aaf5e482730" 
Version="2.0" IssueInstant="2013-03-18T03:28:54.1839884Z" 
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://www.contoso.com</Issuer>
</samlp:AuthnRequest>

AuthnRequest Element

To request a user authentication, cloud services send an AuthnRequest element to Azure Active Directory. The following list describes the required, optional, and ignored attributes when the AuthnRequest element is used in this context.

  • Required Attributes

    • ID. Azure Active Directory uses the value of the ID attribute to populate the InResponseTo attribute of the SAML Response that it returns. The SAML specification requires that the value of ID must not begin with a number. A common strategy to generate a value for the ID attribute is to prepend a predefined string, such as "id", to the string representation of a GUID.

    • Version. Set the value of the version attribute to 2.0. This value is required.

    • IssueInstant. Set the value of the IssueInstant attribute to a DateTime string with a Coordinated Universal Time (UTC) value and round-trip format ("o"). Azure Active Directory expects a Datetime value of this type, but does not evaluate or use the value.

  • Optional Attributes

    • AssertionConsumerServiceURL. If provided, the value of the AssertionConsumerServiceURL attribute must exactly match the value of the RedirectUri of the service principal object that represents the cloud service in Azure Active Directory.

    • ForceAuthn: If provided, set the value to false. Any other value causes an error.

    • IsPassive: If provided, set the value to false. Any other value causes an error.

  • Ignored Attributes: Consent, Destination, AssertionConsumerServiceIndex, AttributeConsumerServiceIndex, ProviderName

Conditions Element in AuthnRequest

Azure Active Directory ignores the Conditions element in an AuthnRequest element.

Issuer Element in AuthnRequest

The Issuer element is required in any AuthnRequest element sent to Azure Active Directory.

The following SAML excerpt shows a sample Issuer element.

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://www.contoso.com</Issuer>

The value of the Issuer element must exactly match one of the ServicePrincipalNames in the service principal object that represents the cloud service in Azure Active Directory. Set the value of the Issuer element to the App ID URI that is specified during application registration.

NameIDPolicy Element in AuthnRequest

The NameIDPolicy element, which requests a particular name ID format, is optional in AuthnRequest elements sent to Azure Active Directory.

If NameIDPolicy is provided, you can include its optional Format attribute. If provided, the Format attribute must have one of the following values. Any other value results in an error.

  • "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent": Azure Active Directory issues the NameID claim as a pairwise identifier.

  • "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress": Azure Active Directory issues the NameID claim in e-mail address format.

  • "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified": This value permits Azure Active Directory to select the claim format. Azure Active Directory issues the NameID as a pairwise identifier.

Do not include the SPNameQualifier attribute. If you include the AllowCreate attribute, Azure Active Directory doesn't return an error, but the element is ignored.

The following is an example of a valid NameIdPolicy element.

<NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"/>

RequestedAuthnContext Element

The RequestedAuthnContext element specifies the desired authentication methods. It is optional in AuthnRequest elements sent to Azure Active Directory. Azure Active Directory supports only one AuthnContextClassRef (request of authentication context class) value, "urn:oasis:names:tc:SAML:2.0:ac:classes:Password".

Scoping Element in AuthnRequest

The Scoping element, which includes a list of identity providers, is optional in AuthnRequest elements sent to Azure Active Directory.

Do not include the ProxyCount attribute, IDPList option, or the RequesterID element, in the Scoping element of an AuthnRequest sent to Azure Active Directory. They are not supported.

Signature Element in AuthnRequest

Do not include a Signature element in an AuthnRequest sent to Azure Active Directory. Azure Active Directory does not support signed authentication requests.

Subject Element in AuthnRequest

Azure Active Directory ignores Subject element of AuthnRequest elements.

Response

When a requested sign-on completes successfully, Azure Active Directory posts a response to the cloud service (service provider). This section describes the format of the response. The following SAML sample shows the response to a successful sign-on attempt.

<samlp:Response ID="_a4958bfd-e107-4e67-b06d-0d85ade2e76a" Version="2.0" IssueInstant="2013-03-18T07:38:15.144Z" Destination="https://contoso.com/identity/inboundsso.aspx" InResponseTo="id758d0ef385634593a77bdf7e632984b6" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"> https://login.microsoftonline.com/82869000-6ad1-48f0-8171-272ed18796e9/</Issuer>
  <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
    ...
  </ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <Assertion ID="_bf9c623d-cc20-407a-9a59-c2d0aee84d12" IssueInstant="2013-03-18T07:38:15.144Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
    <Issuer>https://login.microsoftonline.com/82869000-6ad1-48f0-8171-272ed18796e9/</Issuer>
    <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
      ...
    </ds:Signature>
    <Subject>
      <NameID>Uz2Pqz1X7pxe4XLWxV9KJQ+n59d573SepSAkuYKSde8=</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="id758d0ef385634593a77bdf7e632984b6" NotOnOrAfter="2013-03-18T07:43:15.144Z" Recipient="https://contoso.com/identity/inboundsso.aspx" />
      </SubjectConfirmation>
    </Subject>
    <Conditions NotBefore="2013-03-18T07:38:15.128Z" NotOnOrAfter="2013-03-18T08:48:15.128Z">
      <AudienceRestriction>
        <Audience>https://www.contoso.com</Audience>
      </AudienceRestriction>
    </Conditions>
    <AttributeStatement>
      <Attribute Name="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>testuser@contoso.com</AttributeValue>
      </Attribute>
      <Attribute Name="https://schemas.microsoft.com/identity/claims/objectidentifier">
        <AttributeValue>3F2504E0-4F89-11D3-9A0C-0305E82C3301</AttributeValue>
      </Attribute>
      ...
    </AttributeStatement>
    <AuthnStatement AuthnInstant="2013-03-18T07:33:56.000Z" SessionIndex="_bf9c623d-cc20-407a-9a59-c2d0aee84d12">
      <AuthnContext>
        <AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
      </AuthnContext>
    </AuthnStatement>
  </Assertion>
</samlp:Response>

Response Element

The Response element includes the results of the authorization request. Azure Active Directory includes the ID, Version and IssueInstant attributes of the Response element. It also sets the values of the following attributes.

  • Destination: When sign-on completes successfully, Azure Active Directory sets the value of the Destination attribute to the RedirectUri of the service provider.

  • InResponseTo: Azure Active Directory always sets the value of InResponseTo attribute to the value of the ID attribute of the AuthnRequest element that initiated the response.

Issuer Element in Response Element

Azure Active Directory sets the value of Issuer element to "https://login.microsoftonline.com/<TenantIDGUID>/" where <TenantIDGUID> is the Tenant ID of the Azure Active Directory tenant.

The following SAML excerpt shows a sample Issuer element.

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"> https://login.microsoftonline.com/82869000-6ad1-48f0-8171-272ed18796e9/</Issuer>

Signature Element in Response

Azure Active Directory signs the Response element in response to a successful sign-on. The Signature element in the Response element contains a digital signature that the cloud service can use to authenticate the source and verity the integrity of the response. To generate this digital signature, Azure Active Directory uses the signing key specified in the IDPSSODescriptor element of its metadata document.

Azure Active Directory also signs the Assertion element in the Response element, but the two Signature elements are independent.

The following SAML excerpt shows a sample Signature element. In this sample, the digital signature is replaced by ellipses.

<ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
    ...
  </ds:Signature>

For more information about the IDPSSODescriptor element, see SAML Protocol Metadata and Endpoints.

Status Element in Response

Azure Active Directory uses the Status element to convey the success or failure of sign-on. The StatusCode element in the Status element contains a code or a set of nested codes that represent the status of the request. The Status element also includes the StatusMessage element, which contains custom error messages that are generated during the sign-on process.

For more information about the authentication errors that Azure Active Directory returns, see Authentication Protocol Error Reference.

The following SAML excerpt shows a sample SAML response to an unsuccessful sign-on attempt.

<samlp:Response ID="_f0961a83-d071-4be5-a18c-9ae7b22987a4" Version="2.0" IssueInstant="2013-03-18T08:49:24.405Z" InResponseTo="iddce91f96e56747b5ace6d2e2aa9d4f8c" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://sts.windows.net/82869000-6ad1-48f0-8171-272ed18796e9/</Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester">
      <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported" />
    </samlp:StatusCode>
    <samlp:StatusMessage>AADSTS75006: An error occurred while processing a SAML2 Authentication request. AADSTS90011: The SAML authentication request property 'NameIdentifierPolicy/SPNameQualifier' is not supported.
Trace ID: 66febed4-e737-49ff-ac23-464ba090d57c
Timestamp: 2013-03-18 08:49:24Z</samlp:StatusMessage>
  </samlp:Status>

Assertion Element in Response

Azure Active Directory sets the following attributes on the Assertion element in the Response element: ID, IssueInstant, and Version.

Issuer Element in Assertion

Azure Active Directory sets the value of the Issuer element in the Assertion element to https://sts.windows.net/\<TenantIDGUID>/ where <TenantIDGUID> is the Tenant ID of the Azure Active Directory tenant.

The following SAML excerpt shows a sample Issuer element in the Assertion element.

<Issuer>https://login.microsoftonline.com/82869000-6ad1-48f0-8171-272ed18796e9/</Issuer>

Signature Element in Assertion

Azure Active Directory signs the assertion in a response to a successful sign-on. The Signature element in the Assertion element contains a digital signature that the cloud service can use to authenticate the source verify the integrity of the assertion. To generate this digital signature, Azure Active Directory uses the signing key specified in the IDPSSODescriptor element of its metadata document.

For more information about the IDPSSODescriptor element, see SAML Protocol Metadata and Endpoints.

The following SAML excerpt shows a sample Signature element in the Assertion element. In this sample, the digital signature is replaced by ellipses.

<ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
      ...
    </ds:Signature>

Subject Element in Assertion

The Subject element of the Assertion element in an Azure Active Directory response specifies the principal that is the subject of the statements in the assertion.

The Subject element in a response returned by Azure Active Directory contains the NameId and SubjectConfirmation elements.

The value of NameId element is an opaque and immutable identifier that represents the authenticated user. The NameId value is a targeted identifier that is directed only to the service provider that is the audience for the token. The NameId value is persistent; it can be revoked, but is never reassigned. It is also opaque, that is, it does not reveal anything about the user and it cannot be used as an identifier for attribute queries.

The following SAML excerpt shows a sample Subject element.

<Subject>
      <NameID>Uz2Pqz1X7pxe4XLWxV9KJQ+n59d573SepSAkuYKSde8=</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="id758d0ef385634593a77bdf7e632984b6" NotOnOrAfter="2013-03-18T07:43:15.144Z" Recipient="https://contoso.com/identity/inboundsso.aspx" />
      </SubjectConfirmation>
    </Subject>

Azure Active Directory sets the Method attribute of the SubjectConfirmation element only to "urn:oasis:names:tc:SAML:2.0:cm:bearer".

Conditions Element in Assertion

The Conditions element in the Assertion element specifies conditions that define the acceptable use of SAML assertions.

The following SAML excerpt shows a sample Conditions element.

<Conditions NotBefore="2013-03-18T07:38:15.128Z" NotOnOrAfter="2013-03-18T08:48:15.128Z">
      <AudienceRestriction>
        <Audience>https://www.contoso.com</Audience>
      </AudienceRestriction>
    </Conditions>

Azure Active Directory sets the NotBefore and NotOnOrAfter attributes of the Conditions element of the Assertion element. These attributes specify the interval during which the assertion is valid.

  • The value of the NotBefore attribute is equal to or slightly (less than a second) later than the value of IssueInstant attribute of the Assertion element. Azure Active Directory does not account for any time difference between itself and the cloud service (service provider), and does not add any buffer to this time.

  • The value of the NotOnOrAfter attribute is 70 minutes later than the value of the NotBefore attribute.

Audience Element in Assertion

The Audience element appears in the AudienceRestriction element of the Conditions element in the response assertion . The value of Audience is a URI that identifies an intended audience. Azure Active Directory sets the value of the Audience element to the value of Issuer element of the AuthnRequest that initiated the sign-on. The issuer of the authentication request is the audience for the response.

The following SAML excerpt shows a sample Audience element in an AudienceRestriction element.

<AudienceRestriction>
        <Audience>https://www.contoso.com</Audience>
      </AudienceRestriction>

Like the Issuer value, the Audience value must exactly match one of the service principal names that represents the cloud service in Azure Active Directory. However, if the value of the Issuer element in the AuthnRequest element is not a URI value, the Audience value in the response is the Issuer value prefixed with spn:.

To evaluate the Audience value, use the value of the App ID URI that was specified during application registration.

AttributeStatement Element in Assertion

The AttributeStatement element contains claims about the subject or user.

The following SAML excerpt is a sample AttributeStatement element. The ellipsis indicates that the element can include multiple attributes and attribute values.

<AttributeStatement>
      <Attribute Name="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>testuser@contoso.com</AttributeValue>
      </Attribute>
      <Attribute Name="https://schemas.microsoft.com/identity/claims/objectidentifier">
        <AttributeValue>3F2504E0-4F89-11D3-9A0C-0305E82C3301</AttributeValue>
      </Attribute>
      ...
    </AttributeStatement>

Azure Active Directory adds multiple claims about the authenticated user to the value of the AttributeStatement element, including Name and ObjectIdentifier claims

  • Name Claim. The value of the Name attribute (https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) is the user principal name of the authenticated user, such as testuser@managedtenant.com.

  • ObjectIdentifier Claim. The value of the ObjectIdentifier attribute "https://schemas.microsoft.com/identity/claims/objectidentifier" is the ObjectId of the directory object that represents the authenticated user in Azure Active Directory. ObjectId is an immutable, globally unique, and re-use safe identifier of the authenticated user.

For more information about the claim types that Azure Active Directory supports, see Supported Token and Claim Types.

AuthnStatement Element in Assertion

The AuthnStatement asserts that the assertion subject was authenticated by a particular means at a particular time. The AuthnInstant attribute of the AuthnStatement element specifies the time at which the user authenticated with Azure Active Directory. The AuthnStatement element also contains the AuthnContext element, which specifies the class of the authentication context used to authenticate the user.

The following shows a sample AuthnStatement element.

<AuthnStatement AuthnInstant="2013-03-18T07:33:56.000Z" SessionIndex="_bf9c623d-cc20-407a-9a59-c2d0aee84d12">
      <AuthnContext>
        <AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
      </AuthnContext>
    </AuthnStatement>

See Also

SAML Protocol Reference
SAML Protocol Metadata and Endpoints
Single Sign-out (SAML Protocol)
Active Directory Authentication Protocols