Protokół SAML logowania jednokrotnego

  • Artykuł

W tym artykule opisano żądania uwierzytelniania SAML 2.0 i odpowiedzi obsługiwane przez usługę Microsoft Entra ID na potrzeby logowania jednokrotnego.

Na poniższym diagramie protokołu opisano sekwencję logowania jednokrotnego. Usługa w chmurze (dostawca usług) używa powiązania przekierowania HTTP, aby przekazać AuthnRequest element (żądanie uwierzytelniania) do identyfikatora Entra firmy Microsoft (dostawcy tożsamości). Następnie identyfikator Entra firmy Microsoft używa powiązania post HTTP, aby opublikować Response element w usłudze w chmurze.

Zrzut ekranu przedstawiający przepływ pracy logowania jednokrotnego.

Uwaga

W tym artykule omówiono używanie protokołu SAML na potrzeby logowania jednokrotnego. Aby uzyskać więcej informacji na temat innych sposobów obsługi logowania jednokrotnego (na przykład przy użyciu interfejsu OpenID Połączenie lub zintegrowanego uwierzytelniania systemu Windows), zobacz Logowanie jednokrotne do aplikacji w usłudze Microsoft Entra ID.

AuthnRequest

Aby zażądać uwierzytelniania użytkownika, usługi w chmurze wysyłają AuthnRequest element do identyfikatora Entra firmy Microsoft. Przykładowy plik SAML 2.0 AuthnRequest może wyglądać podobnie do następującego przykładu:

<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>
Parametr Type Opis
ID Wymagania Identyfikator Entra firmy Microsoft używa tego atrybutu do wypełnienia InResponseTo atrybutu zwróconej odpowiedzi. Identyfikator nie może zaczynać się od liczby, dlatego typową strategią jest utworzenie ciągu takiego jak "ID" do ciągu reprezentującego identyfikator GUID. Na przykład id6c1c178c166d486687be4aaf5e482730 jest prawidłowym identyfikatorem.
Version Wymagania Ten parametr powinien być ustawiony na 2.0wartość .
IssueInstant Wymagania Jest to ciąg Typu data/godzina z wartością UTC i formatem dwukierunkowym ("o").. Identyfikator Entra firmy Microsoft oczekuje wartości DateTime tego typu, ale nie oblicza ani nie używa wartości.
AssertionConsumerServiceURL Opcjonalnie Jeśli zostanie podany, ten parametr musi być zgodny RedirectUri z usługą w chmurze w identyfikatorze Entra firmy Microsoft.
ForceAuthn Opcjonalnie Jest to wartość logiczna. Jeśli to prawda, oznacza to, że użytkownik zostanie zmuszony do ponownego uwierzytelnienia, nawet jeśli ma prawidłową sesję z identyfikatorem Entra firmy Microsoft.
IsPassive Opcjonalnie Jest to wartość logiczna określająca, czy identyfikator Entra firmy Microsoft powinien uwierzytelniać użytkownika w trybie dyskretnym, bez interakcji użytkownika, używając pliku cookie sesji, jeśli istnieje. Jeśli tak jest, identyfikator Entra firmy Microsoft próbuje uwierzytelnić użytkownika przy użyciu pliku cookie sesji.

Wszystkie inne AuthnRequest atrybuty, takie jak Consent, Destination, AssertionConsumerServiceIndex, AttributeConsumerServiceIndexi ProviderName , są ignorowane.

Identyfikator Entra firmy Microsoft ignoruje również element w elemecie ConditionsAuthnRequest.

Wystawca

Element Issuer w elemecie AuthnRequest musi dokładnie odpowiadać jednemu z parametrów ServicePrincipalNames w usłudze w chmurze w identyfikatorze Entra firmy Microsoft. Zazwyczaj jest to ustawienie identyfikatora URI identyfikatora aplikacji określonego podczas rejestracji aplikacji.

Fragment SAML zawierający Issuer element wygląda podobnie do następującego przykładu:

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

NameIDPolicy

Ten element żąda określonego formatu identyfikatora nazwy w odpowiedzi i jest opcjonalny w AuthnRequest elementach wysyłanych do identyfikatora Entra firmy Microsoft.

Element NameIdPolicy wygląda podobnie do następującego przykładu:

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

Jeśli NameIDPolicy zostanie podany, możesz uwzględnić jego opcjonalny Format atrybut. Atrybut może mieć tylko jedną z następujących wartości; każda Format inna wartość powoduje błąd.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: Identyfikator Entra firmy Microsoft wystawia NameID oświadczenie jako identyfikator parowania.
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: Identyfikator entra firmy Microsoft wystawia NameID oświadczenie w formacie adresu e-mail.
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: Ta wartość umożliwia firmie Microsoft Entra ID wybranie formatu oświadczenia. Identyfikator Entra firmy Microsoft wystawia NameID oświadczenie jako identyfikator parowania.
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient: Identyfikator Entra firmy Microsoft wystawia NameID oświadczenie jako losowo wygenerowaną wartość, która jest unikatowa dla bieżącej operacji logowania jednokrotnego. Oznacza to, że wartość jest tymczasowa i nie można jej używać do identyfikowania uwierzytelniającego użytkownika.

Jeśli SPNameQualifier zostanie określony, identyfikator Entra firmy Microsoft zawiera tę samą SPNameQualifier wartość w odpowiedzi.

Identyfikator Entra firmy Microsoft ignoruje AllowCreate atrybut .

RequestedAuthnContext

Element RequestedAuthnContext określa żądane metody uwierzytelniania. Jest on opcjonalny w AuthnRequest elementach wysyłanych do identyfikatora Entra firmy Microsoft. Identyfikator entra firmy Microsoft obsługuje AuthnContextClassRef wartości, takie jak urn:oasis:names:tc:SAML:2.0:ac:classes:Password.

Określanie zakresu

Element Scoping , który zawiera listę dostawców tożsamości, jest opcjonalny w AuthnRequest elementach wysyłanych do identyfikatora Entra firmy Microsoft.

Jeśli zostanie podany, nie uwzględnij atrybutu ProxyCountIDPListOption ani RequesterID elementu, ponieważ nie są one obsługiwane.

Podpis

Element Signature w AuthnRequest elementach jest opcjonalny. Usługę Microsoft Entra ID można skonfigurować w celu wymuszania wymagania podpisanych żądań uwierzytelniania. Jeśli to ustawienie jest włączone, akceptowane są tylko podpisane żądania uwierzytelniania. W przeciwnym razie weryfikacja osoby żądającej jest zapewniana tylko przez odpowiadanie na zarejestrowane adresy URL usługi Assertion Consumer Service.

Temat

Nie dołączaj Subject elementu. Identyfikator Entra firmy Microsoft nie obsługuje określania tematu w AuthnRequest pliku i zwróci błąd, jeśli zostanie podany.

Zamiast tego można podać temat, dodając login_hint parametr do żądania HTTP do adresu URL logowania jednokrotnego z identyfikatorem NameID podmiotu jako wartością parametru.

Response

Po pomyślnym zakończeniu żądanego logowania identyfikator Entra firmy Microsoft publikuje odpowiedź na usługę w chmurze. Odpowiedź na pomyślną próbę logowania wygląda następująco:

<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/aaaabbbb-0000-cccc-1111-dddd2222eeee/</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/aaaabbbb-0000-cccc-1111-dddd2222eeee/</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

Element Response zawiera wynik żądania autoryzacji. Identyfikator Entra firmy Microsoft ustawia IDVersion wartości i IssueInstant w elemecie Response . Ustawia również następujące atrybuty:

  • Destination: Po pomyślnym zakończeniu logowania jest on ustawiony na RedirectUri dostawcę usług (usługę w chmurze).
  • InResponseTo: Jest on ustawiony na ID atrybut AuthnRequest elementu, który zainicjował odpowiedź.

Wystawca

Identyfikator entra firmy Microsoft ustawia Issuer element na https://sts.windows.net/<TenantIDGUID>/ gdzie <TenantIDGUID> jest identyfikatorem dzierżawy firmy Microsoft Entra.

Na przykład odpowiedź z elementem Wystawca może wyglądać podobnie do następującego przykładu:

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"> https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>

Stan

Element Status przekazuje powodzenie lub niepowodzenie logowania. Zawiera StatusCode element, który zawiera kod lub zestaw zagnieżdżonych kodów, który reprezentuje stan żądania. Zawiera StatusMessage również element zawierający niestandardowe komunikaty o błędach generowane podczas procesu logowania.

Poniższy przykład to odpowiedź SAML na nieudaną próbę logowania.

<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/aaaabbbb-0000-cccc-1111-dddd2222eeee/</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: 0000aaaa-11bb-cccc-dd33-eeeeee333333
    Timestamp: 2013-03-18 08:49:24Z</samlp:StatusMessage>
    </samlp:Status>
</samlp:Response>

Asercja

Oprócz wartości ID, IssueInstant i Versionidentyfikator Entra firmy Microsoft ustawia następujące elementy w Assertion elemecie odpowiedzi.

Wystawca

Jest ona ustawiona na https://sts.windows.net/<TenantIDGUID>/lokalizację, w której <TenantIDGUID> jest identyfikator dzierżawy firmy Microsoft Entra.

<Issuer>https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>

Podpis

Identyfikator Firmy Microsoft Entra podpisuje asercję w odpowiedzi na pomyślne zalogowanie. Element Signature zawiera podpis cyfrowy, którego usługa w chmurze może użyć do uwierzytelnienia źródła w celu zweryfikowania integralności asercji.

Aby wygenerować ten podpis cyfrowy, identyfikator Entra firmy Microsoft używa klucza podpisywania w IDPSSODescriptor elemecie dokumentu metadanych.

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

Temat

Określa zasadę, która jest przedmiotem stwierdzeń w twierdzeniu. Zawiera NameID element reprezentujący uwierzytelnionego użytkownika. Wartość NameID jest identyfikatorem docelowym, który jest kierowany tylko do dostawcy usług, który jest odbiorcą tokenu. Jest on trwały — można go odwołać, ale nigdy nie jest ponownie przypisywany. Jest on również nieprzezroczystym, ponieważ nie ujawnia żadnych informacji o użytkowniku i nie może być używany jako identyfikator zapytań atrybutów.

Atrybut MethodSubjectConfirmation elementu jest zawsze ustawiony na urn:oasis:names:tc:SAML:2.0:cm:bearerwartość .

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

Warunki

Ten element określa warunki, które definiują akceptowalne użycie asercji SAML.

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

Atrybuty NotBefore i NotOnOrAfter określają interwał, w którym potwierdzenie jest prawidłowe.

  • Wartość atrybutu NotBefore jest równa lub nieco (mniejsza niż sekunda) później niż wartość IssueInstant atrybutu Assertion elementu. Microsoft Entra ID nie uwzględnia żadnej różnicy czasu między samym sobą a usługą w chmurze (dostawcą usług) i nie dodaje żadnego buforu do tej pory.
  • Wartość atrybutu NotOnOrAfter wynosi 70 minut później niż wartość atrybutu NotBefore .

Odbiorcy

Zawiera on identyfikator URI, który identyfikuje zamierzonych odbiorców. Microsoft Entra ID ustawia wartość tego elementu na wartość Issuer elementu AuthnRequest , który zainicjował logowanie. Aby ocenić Audience wartość, użyj wartości App ID URI określonej podczas rejestracji aplikacji.

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

Issuer Podobnie jak wartość, Audience wartość musi być dokładnie zgodna z jedną z głównych nazw usługi, która reprezentuje usługę w chmurze w identyfikatorze Entra firmy Microsoft. Jeśli jednak wartość Issuer elementu nie jest wartością identyfikatora URI, Audience wartość w odpowiedzi jest Issuer wartością poprzedzoną prefiksem spn:.

AtrybutStatement

Zawiera on oświadczenia dotyczące tematu lub użytkownika. Poniższy fragment zawiera przykładowy AttributeStatement element. Wielokropek wskazuje, że element może zawierać wiele atrybutów i wartości atrybutów.

<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 Claim — wartość atrybutu Name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) jest główną nazwą użytkownika uwierzytelnionego, na przykład testuser@managedtenant.com.
  • ObjectIdentifier Claim — wartość atrybutu ObjectIdentifier (http://schemas.microsoft.com/identity/claims/objectidentifier) jest ObjectId obiektem katalogu reprezentującym uwierzytelnionego użytkownika w identyfikatorze Entra firmy Microsoft. ObjectId jest niezmiennym, globalnie unikatowym i ponownie używanym bezpiecznym identyfikatorem uwierzytelnionego użytkownika.

AuthnStatement

Ten element potwierdza, że podmiot asercji został uwierzytelniony za pomocą określonych środków w określonym czasie.

  • Atrybut AuthnInstant określa czas, w którym użytkownik uwierzytelnił się za pomocą identyfikatora Entra firmy Microsoft.
  • Element AuthnContext określa kontekst uwierzytelniania używany do uwierzytelniania użytkownika.
<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>