單一登入 SAML 通訊協定Single Sign-On SAML protocol

本文涵蓋 Azure Active Directory (Azure AD) 針對單一登入所支援的 SAML 2.0 驗證要求和回應。This article covers the SAML 2.0 authentication requests and responses that Azure Active Directory (Azure AD) supports for Single Sign-On.

下面的通訊協定圖表說明單一登入順序。The protocol diagram below describes the single sign-on sequence. 雲端服務 (服務提供者) 使用 HTTP 重新導向繫結傳遞 AuthnRequest (驗證要求) 元素至 Azure AD (識別提供者)。The cloud service (the service provider) uses an HTTP Redirect binding to pass an AuthnRequest (authentication request) element to Azure AD (the identity provider). Azure AD 接著使用 HTTP POST 繫結將 Response 元素張貼至雲端服務。Azure AD then uses an HTTP post binding to post a Response element to the cloud service.

單一登入工作流程

AuthnRequestAuthnRequest

為了要求使用者驗證,雲端服務會將 AuthnRequest 元素傳送至 Azure AD。To request a user authentication, cloud services send an AuthnRequest element to Azure AD. SAML 2.0 AuthnRequest 範例會像下面這樣:A sample SAML 2.0 AuthnRequest could look like the following example:

<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>
參數Parameter 描述Description
idID 必要項Required Azure AD 使用這個屬性來填入所傳回回應的 InResponseTo 屬性。Azure AD uses this attribute to populate the InResponseTo attribute of the returned response. 識別碼的開頭不能是數字,因此常見的策略是在 GUID 的字串表示法前面加上 "id" 等字串。ID must not begin with a number, so a common strategy is to prepend a string like "id" to the string representation of a GUID. 例如, id6c1c178c166d486687be4aaf5e482730 便是有效的識別碼。For example, id6c1c178c166d486687be4aaf5e482730 is a valid ID.
VersionVersion 必要項Required 此參數應該設定為 2.0This parameter should be set to 2.0.
IssueInstantIssueInstant 必要項Required 這是具有 UTC 值和 來回行程格式 ("o")的日期時間字串。This is a DateTime string with a UTC value and round-trip format ("o"). Azure AD 必須要有這種類型的日期時間值,但不會評估或使用此值。Azure AD expects a DateTime value of this type, but doesn't evaluate or use the value.
AssertionConsumerServiceUrlAssertionConsumerServiceUrl 選擇性Optional 如果提供,此參數必須符合 Azure AD 中雲端服務的 RedirectUriIf provided, this parameter must match the RedirectUri of the cloud service in Azure AD.
ForceAuthnForceAuthn 選擇性Optional 這是布林值。This is a boolean value. 如果為 true,表示即使使用者在 Azure AD 中具有有效的工作階段,也會強制使用者重新驗證。If true, it means that the user will be forced to re-authenticate, even if they have a valid session with Azure AD.
IsPassiveIsPassive 選擇性Optional 這是布林值,指定 Azure AD 是否以無訊息模式驗證使用者,不需要使用者互動,如果有工作階段 cookie 的話則使用此 cookie。This is a boolean value that specifies whether Azure AD should authenticate the user silently, without user interaction, using the session cookie if one exists. 如果是這種情況,Azure AD 會嘗試使用工作階段 cookie 驗證使用者。If this is true, Azure AD will attempt to authenticate the user using the session cookie.

其他所有 AuthnRequest 屬性 (例如 Consent、Destination、AssertionConsumerServiceIndex、AttributeConsumerServiceIndex 和 ProviderName) 會 遭到忽略All other AuthnRequest attributes, such as Consent, Destination, AssertionConsumerServiceIndex, AttributeConsumerServiceIndex, and ProviderName are ignored.

Azure AD 也會忽略 AuthnRequest 中的 Conditions 元素。Azure AD also ignores the Conditions element in AuthnRequest.

簽發者Issuer

AuthnRequest 中的 Issuer 元素必須完全符合 Azure AD 中雲端服務的其中一個 ServicePrincipalNamesThe Issuer element in an AuthnRequest must exactly match one of the ServicePrincipalNames in the cloud service in Azure AD. 一般而言,這會設定為應用程式註冊期間指定的 應用程式識別碼 URITypically, this is set to the App ID URI that is specified during application registration.

包含 Issuer 元素的 SAML 摘錄看起來會像下列範例︰A SAML excerpt containing the Issuer element looks like the following sample:

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

NameIDPolicyNameIDPolicy

這個元素要求回應中使用特定名稱識別碼格式,在傳送至 Azure AD 的 AuthnRequest 元素中是選擇性的。This element requests a particular name ID format in the response and is optional in AuthnRequest elements sent to Azure AD.

NameIdPolicy 元素看起來會像下列範例︰A NameIdPolicy element looks like the following sample:

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

如果提供 NameIDPolicy,您可以包含其選擇性的 Format 屬性。If NameIDPolicy is provided, you can include its optional Format attribute. Format 屬性只能有下列其中一個值;其他任何值都會產生錯誤。The Format attribute can have only 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 發出 NameID 宣告來做為成對識別碼。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 發出電子郵件地址格式的 NameID 宣告。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:這個值允許 Azure Active Directory 選取宣告格式。urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: This value permits Azure Active Directory to select the claim format. Azure Active Directory 發出 NameID 來做為成對識別碼。Azure Active Directory issues the NameID as a pairwise identifier.
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient:Azure Active Directory 發出 NameID 宣告做為隨機產生的值,此值對目前的 SSO 作業來說是唯一值。urn:oasis:names:tc:SAML:2.0:nameid-format:transient: Azure Active Directory issues the NameID claim as a randomly generated value that is unique to the current SSO operation. 這表示此值只是暫時性的,而且不能用來識別驗證的使用者。This means that the value is temporary and cannot be used to identify the authenticating user.

Azure AD 會忽略 AllowCreate 屬性。Azure AD ignores the AllowCreate attribute.

RequestAuthnContextRequestAuthnContext

RequestedAuthnContext 元素會指定所需的驗證方法。The RequestedAuthnContext element specifies the desired authentication methods. 在傳送至 Azure AD 的 AuthnRequest 元素中,它是選擇性的。It is optional in AuthnRequest elements sent to Azure AD. Azure AD 支援AuthnContextClassRef urn:oasis:names:tc:SAML:2.0:ac:classes:Password之類的值。Azure AD supports AuthnContextClassRef values such as urn:oasis:names:tc:SAML:2.0:ac:classes:Password.

範圍Scoping

包含識別提供者清單的 Scoping 元素在傳送至 Azure AD 的 AuthnRequest 元素中是選擇性的。The Scoping element, which includes a list of identity providers, is optional in AuthnRequest elements sent to Azure AD.

如果提供,請勿包含 ProxyCount 屬性、IDPListOptionRequesterID 元素,因為它們不受支援。If provided, don't include the ProxyCount attribute, IDPListOption or RequesterID element, as they aren't supported.

簽章Signature

請勿在 AuthnRequest 元素中包含 Signature 元素,因為 Azure AD 不支援簽署的驗證要求。Don't include a Signature element in AuthnRequest elements, as Azure AD does not support signed authentication requests.

SubjectSubject

Azure AD 會忽略 AuthnRequest 元素中的 Subject 元素。Azure AD ignores the Subject element of AuthnRequest elements.

回應Response

當要求的登入成功完成時,Azure AD 會將回應張貼至雲端服務。When a requested sign-on completes successfully, Azure AD posts a response to the cloud service. 登入嘗試成功的回應看起來會像下列範例︰A response to a successful sign-on attempt looks like the following sample:

<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="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>testuser@contoso.com</AttributeValue>
      </Attribute>
      <Attribute Name="http://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

Response 元素包含授權要求的結果。The Response element includes the result of the authorization request. Azure AD 會設定 Response 元素中的 IDVersionIssueInstant 值。Azure AD sets the ID, Version and IssueInstant values in the Response element. 它也會設定下列屬性︰It also sets the following attributes:

  • Destination:當登入順利完成時,這會設定為服務提供者 (雲端服務) 的 RedirectUriDestination: When sign-on completes successfully, this is set to the RedirectUri of the service provider (cloud service).
  • InResponseTo:這會設定為起始回應的 AuthnRequest 元素的 ID 屬性。InResponseTo: This is set to the ID attribute of the AuthnRequest element that initiated the response.

簽發者Issuer

Azure AD 將Issuer元素設定為https://login.microsoftonline.com/<TenantIDGUID>/ , <其中 TenantIDGUID > 是 Azure AD 租使用者的租使用者識別碼。Azure AD sets the Issuer element to https://login.microsoftonline.com/<TenantIDGUID>/ where <TenantIDGUID> is the tenant ID of the Azure AD tenant.

例如,具有 Issuer 元素的回應看起來會像下列範例︰For example, a response with Issuer element could look like the following sample:

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

狀態Status

Status 元素會傳遞登入的成功或失敗。The Status element conveys the success or failure of sign-on. 它包含 StatusCode 元素,此元素中包含一個代碼或一組巢狀代碼來表示要求的狀態。It includes the StatusCode element, which contains a code or a set of nested codes that represents the status of the request. 它也包含 StatusMessage 元素,此元素中包含登入程序期間所產生的自訂錯誤訊息。It also includes the StatusMessage element, which contains custom error messages that are generated during the sign-on process.

下列範例是登入嘗試失敗的 SAML 回應。The following sample is a 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>

AssertionAssertion

除了 IDIssueInstantVersion,Azure AD 還會在回應的 Assertion 元素中設定下列元素。In addition to the ID, IssueInstant and Version, Azure AD sets the following elements in the Assertion element of the response.

簽發者Issuer

這會設定為https://sts.windows.net/<TenantIDGUID>/, <其中 TenantIDGUID > 是 Azure AD 租使用者的租使用者識別碼。This is set to https://sts.windows.net/<TenantIDGUID>/where <TenantIDGUID> is the Tenant ID of the Azure AD tenant.

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

簽章Signature

Azure AD 會簽署判斷提示以回應成功的登入。Azure AD signs the assertion in response to a successful sign-on. Signature 元素包含數位簽章,可供雲端服務用來驗證來源以確認判斷提示的完整性。The Signature element contains a digital signature that the cloud service can use to authenticate the source to verify the integrity of the assertion.

為了產生此數位簽章,Azure AD 會在其中繼資料文件的 IDPSSODescriptor 元素中使用簽署金鑰。To generate this digital signature, Azure AD uses the signing key in the IDPSSODescriptor element of its metadata document.

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

SubjectSubject

這會指定判斷提示中陳述式主旨的主體。This specifies the principal that is the subject of the statements in the assertion. 它包含 NameID 元素,其代表已驗證的使用者。It contains a NameID element, which represents the authenticated user. NameID 值為目標識別碼,其只會導向身為權杖對象的服務提供者。The NameID value is a targeted identifier that is directed only to the service provider that is the audience for the token. 它是持續性的 - 可撤銷,但絕對不會重新指派。It is persistent - it can be revoked, but is never reassigned. 它也是不透明的,因為它不會揭露使用者的相關資訊,也不能當做屬性查詢的識別碼。It is also opaque, in that it does not reveal anything about the user and cannot be used as an identifier for attribute queries.

SubjectConfirmation 元素的 Method 屬性一律會設定為 urn:oasis:names:tc:SAML:2.0:cm:bearerThe Method attribute of the SubjectConfirmation element is always set to urn:oasis:names:tc:SAML:2.0:cm:bearer.

<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

這個元素會指定條件來定義可接受的 SAML 判斷提示用法。This element specifies conditions that define the acceptable use of SAML assertions.

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

NotBeforeNotOnOrAfter 屬性會指定判斷提示的有效間隔期間。The NotBefore and NotOnOrAfter attributes specify the interval during which the assertion is valid.

  • NotBefore 屬性值等於或稍微晚於 (不到一秒) Assertion 元素的 IssueInstant 屬性值。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 AD 不會考慮本身與雲端服務 (服務提供者) 之間的任何時間差,而且不會對此時間加上任何緩衝。Azure AD does not account for any time difference between itself and the cloud service (service provider), and does not add any buffer to this time.
  • NotOnOrAfter 屬性值比 NotBefore 屬性值晚 70 分鐘。The value of the NotOnOrAfter attribute is 70 minutes later than the value of the NotBefore attribute.

對象Audience

這包含可識別適用對象的 URI。This contains a URI that identifies an intended audience. Azure AD 會將這個元素的值設定為起始登入的 AuthnRequestIssuer 元素值。Azure AD sets the value of this element to the value of Issuer element of the AuthnRequest that initiated the sign-on. 若要評估 Audience 值,請使用應用程式註冊期間指定的 App ID URI 值。To evaluate the Audience value, use the value of the App ID URI that was specified during application registration.

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

Issuer 值一樣,Audience 值必須完全符合代表 Azure AD 中雲端服務的其中一個服務主體名稱。Like the Issuer value, the Audience value must exactly match one of the service principal names that represents the cloud service in Azure AD. 不過,如果 Issuer 元素值不是 URI 值,回應中的 Audience 值是前面加上 spn:Issuer 值。However, if the value of the Issuer element is not a URI value, the Audience value in the response is the Issuer value prefixed with spn:.

AttributeStatementAttributeStatement

這包含有關主體或使用者的宣告。This contains claims about the subject or user. 下列摘錄包含範例 AttributeStatement 元素。The following excerpt contains a sample AttributeStatement element. 省略符號表示此元素可能包含多個屬性和屬性值。The ellipsis indicates that the element can include multiple attributes and attribute values.

<AttributeStatement>
      <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>testuser@contoso.com</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
        <AttributeValue>3F2504E0-4F89-11D3-9A0C-0305E82C3301</AttributeValue>
      </Attribute>
      ...
</AttributeStatement>
  • Name 宣告 - Name 屬性的值 (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) 是已驗證使用者的使用者主體名稱,例如 testuser@managedtenant.comName Claim - The value of the Name attribute (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) is the user principal name of the authenticated user, such as testuser@managedtenant.com.
  • ObjectIdentifier 宣告 - ObjectIdentifier 屬性的值 (http://schemas.microsoft.com/identity/claims/objectidentifier) 是目錄物件的 ObjectId,代表 Azure AD 中已驗證的使用者。ObjectIdentifier Claim - The value of the ObjectIdentifier attribute (http://schemas.microsoft.com/identity/claims/objectidentifier) is the ObjectId of the directory object that represents the authenticated user in Azure AD. ObjectId 是不可變的、全域唯一的,且重複使用已驗證使用者的安全識別碼。ObjectId is an immutable, globally unique, and reuse safe identifier of the authenticated user.

AuthnStatementAuthnStatement

此元素會宣稱判斷提示主體已在特定時間以特定方式進行驗證。This element asserts that the assertion subject was authenticated by a particular means at a particular time.

  • AuthnInstant 屬性會指定使用者向 Azure AD 驗證的時間。The AuthnInstant attribute specifies the time at which the user authenticated with Azure AD.
  • AuthnContext 元素會指定用來驗證使用者的驗證內容。The AuthnContext element specifies the authentication context used to authenticate the user.
<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>