SAML-protocol voor eenmalige aanmelding

  • Artikel

In dit artikel worden de SAML 2.0-verificatieaanvragen en -antwoorden beschreven die door Microsoft Entra ID worden ondersteund voor eenmalige aanmelding (SSO).

In het volgende protocoldiagram wordt de reeks eenmalige aanmelding beschreven. De cloudservice (de serviceprovider) maakt gebruik van een HTTP-omleidingsbinding om een AuthnRequest element (verificatieaanvraag) door te geven aan Microsoft Entra ID (de id-provider). Microsoft Entra-id gebruikt vervolgens een HTTP-postbinding om een Response element te posten in de cloudservice.

Schermopname van de werkstroom voor eenmalige aanmelding (SSO).

Notitie

In dit artikel wordt besproken hoe u SAML gebruikt voor eenmalige aanmelding. Zie Eenmalige aanmelding bij toepassingen in Microsoft Entra ID voor meer informatie over andere manieren om eenmalige aanmelding te verwerken (bijvoorbeeld met behulp van OpenID Verbinding maken of geïntegreerde Windows-verificatie).

AuthnRequest

Als u een gebruikersverificatie wilt aanvragen, verzenden cloudservices een AuthnRequest element naar de Microsoft Entra-id. Een voorbeeld van een SAML 2.0-AuthnRequest kan eruitzien als in het volgende voorbeeld:

<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 Type Beschrijving
ID Vereist Microsoft Entra ID gebruikt dit kenmerk om het InResponseTo kenmerk van het geretourneerde antwoord te vullen. De id mag niet beginnen met een getal, dus een algemene strategie is om een tekenreeks zoals 'ID' toe te voegen aan de tekenreeksweergave van een GUID. id6c1c178c166d486687be4aaf5e482730 is bijvoorbeeld een geldige id.
Version Vereist Deze parameter moet worden ingesteld op 2.0.
IssueInstant Vereist Dit is een Datum/tijd-tekenreeks met een UTC-waarde en retourindeling ('o'). Microsoft Entra ID verwacht een datum/tijd-waarde van dit type, maar evalueert of gebruikt de waarde niet.
AssertionConsumerServiceURL Optioneel Indien opgegeven, moet deze parameter overeenkomen met de RedirectUri cloudservice in Microsoft Entra ID.
ForceAuthn Optioneel Dit is een booleaanse waarde. Als dit het geval is, betekent dit dat de gebruiker gedwongen wordt om opnieuw te verifiëren, zelfs als ze een geldige sessie met Microsoft Entra-id hebben.
IsPassive Optioneel Dit is een booleaanse waarde die aangeeft of Microsoft Entra ID de gebruiker op de achtergrond moet verifiëren, zonder tussenkomst van de gebruiker, met behulp van de sessiecookie als deze bestaat. Als dit waar is, probeert Microsoft Entra ID de gebruiker te verifiëren met behulp van de sessiecooky.

Alle andere AuthnRequest kenmerken, zoals Consent, Destination, AssertionConsumerServiceIndex, en AttributeConsumerServiceIndexworden ProviderNamegenegeerd.

Microsoft Entra ID negeert ook het Conditions element in AuthnRequest.

Verlener

Het Issuer element in een AuthnRequest moet exact overeenkomen met een van de ServicePrincipalNames in de cloudservice in Microsoft Entra ID. Dit is doorgaans ingesteld op de App-id-URI die is opgegeven tijdens de registratie van de toepassing.

Een SAML-fragment met het Issuer-element ziet eruit als in het volgende voorbeeld:

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

NameIDPolicy

Dit element vraagt een bepaalde naam-id-indeling aan in het antwoord en is optioneel in AuthnRequest elementen die naar Microsoft Entra-id worden verzonden.

Een NameIdPolicy-element ziet eruit als in het volgende voorbeeld:

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

Als NameIDPolicy wordt opgegeven, kunt u het bijbehorende optionele Format-kenmerk hierin opnemen. Het Format-kenmerk kan slechts één van de volgende waarden hebben. Elke andere waarde resulteert in een fout.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: Microsoft Entra ID geeft de NameID claim uit als een paargewijze id.
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: Microsoft Entra ID geeft de NameID claim in e-mailadresindeling uit.
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: Met deze waarde kan Microsoft Entra-id de claimindeling selecteren. Microsoft Entra ID geeft de NameID claim uit als een paargewijze id.
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient: Microsoft Entra ID geeft de NameID claim uit als een willekeurig gegenereerde waarde die uniek is voor de huidige SSO-bewerking. Dit betekent dat de waarde tijdelijk is en niet kan worden gebruikt om de verificatiegebruiker te identificeren.

Als SPNameQualifier dit is opgegeven, bevat de Microsoft Entra-id hetzelfde SPNameQualifier in het antwoord.

Microsoft Entra ID negeert het AllowCreate kenmerk.

RequestedAuthnContext

Het RequestedAuthnContext-element geeft de gewenste verificatiemethoden op. Het is optioneel in AuthnRequest elementen die naar Microsoft Entra-id worden verzonden. Microsoft Entra ID ondersteunt AuthnContextClassRef waarden zoals urn:oasis:names:tc:SAML:2.0:ac:classes:Password.

Bereik bepalen

Het Scoping element, dat een lijst met id-providers bevat, is optioneel in AuthnRequest elementen die naar Microsoft Entra-id worden verzonden.

Als dit wordt opgegeven, neemt u het ProxyCount-kenmerk, het IDPListOption- of RequesterID-element niet op, omdat deze niet worden ondersteund.

Handtekening

Een Signature-element bij AuthnRequest-elementen is optioneel. Microsoft Entra ID kan worden geconfigureerd om de vereiste van ondertekende verificatieaanvragen af te dwingen. Indien ingeschakeld, worden alleen ondertekende verificatieaanvragen geaccepteerd, anders wordt de verificatie van de aanvrager verstrekt door alleen te reageren op geregistreerde URL's van Assertion Consumer Service.

Onderwerp

Neem geen Subject-element op. Microsoft Entra ID biedt geen ondersteuning voor het opgeven van een onderwerp in AuthnRequest en retourneert een fout als er een is opgegeven.

Een onderwerp kan in plaats daarvan worden opgegeven door een login_hint-parameter toe te voegen aan de URL van de HTTP-aanvraag voor eenmalige aanmelding, met de NameID van het onderwerp als parameterwaarde.

Respons

Wanneer een aangevraagde aanmelding is voltooid, plaatst Microsoft Entra ID een antwoord op de cloudservice. Een antwoord op een geslaagde aanmeldingspoging ziet eruit als in het volgende voorbeeld:

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

Respons

Het Response-element bevat het resultaat van de autorisatieaanvraag. Microsoft Entra-id stelt de IDen IssueInstantVersion waarden in het Response element in. Ook worden de volgende kenmerken ingesteld:

  • Destination: Wanneer de aanmelding is voltooid, wordt dit ingesteld op de RedirectUri serviceprovider (cloudservice).
  • InResponseTo: dit is ingesteld op het ID-kenmerk van het AuthnRequest-element dat het antwoord heeft geïnitieerd.

Verlener

Microsoft Entra-id stelt het Issuer element in op https://sts.windows.net/<TenantIDGUID>/ de locatie van <TenantIDGUID> de tenant-id van de Microsoft Entra-tenant.

Een antwoord met het Issuer-element kan er bijvoorbeeld uitzien als in het volgende voorbeeld:

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

Status

Het Status-element geeft het succes of falen van de aanmelding aan. Het bevat het StatusCode-element, met een code of een set geneste codes die de status van de aanvraag weergeeft. Het bevat ook het StatusMessage-element, met aangepaste foutberichten die tijdens het aanmeldingsproces worden gegenereerd.

Het volgende voorbeeld is een SAML-antwoord op een mislukte aanmeldingspoging.

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

Assertie

Naast de ID, IssueInstant en Versionstelt Microsoft Entra ID de volgende elementen in het element van het Assertion antwoord in.

Verlener

Dit is ingesteld op https://sts.windows.net/<TenantIDGUID>/waar <TenantIDGUID> de tenant-id van de Microsoft Entra-tenant is.

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

Handtekening

Microsoft Entra ID ondertekent de verklaring als reactie op een geslaagde aanmelding. Het Signature-element bevat een digitale handtekening die de cloudservice kan gebruiken om de bron te verifiëren, zodat de integriteit van de assertie kan worden geverifieerd.

Voor het genereren van deze digitale handtekening gebruikt Microsoft Entra ID de ondertekeningssleutel in het element van het IDPSSODescriptor metagegevensdocument.

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

Onderwerp

Hiermee geeft u het principe aan dat het onderwerp is van de instructies in de verklaring. Het bevat een NameID-element, dat de geverifieerde gebruiker weergeeft. De NameID-waarde is een doel-id die alleen wordt doorgestuurd naar de serviceprovider die de doelgroep voor het token is. Dit is permanent; het kan worden ingetrokken, maar wordt nooit opnieuw toegewezen. De waarde is ook ondoorzichtig, omdat deze niets onthult over de gebruiker en niet kan worden gebruikt als id voor query's naar kenmerken.

Het Method-kenmerk van het SubjectConfirmation-element is altijd ingesteld op 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>

Voorwaarden

Dit element geeft voorwaarden op waarmee het acceptabele gebruik van SAML-asserties wordt gedefinieerd.

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

Het NotBefore- en NotOnOrAfter-kenmerk geven het interval op waarin de assertie geldig is.

  • De waarde van het NotBefore-kenmerk is op hetzelfde tijdstip als of iets (minder dan een seconde) later dan de waarde van het IssueInstant-kenmerk van het Assertion-element. Microsoft Entra ID houdt geen rekening met een tijdsverschil tussen zichzelf en de cloudservice (serviceprovider) en voegt geen buffer toe aan deze tijd.
  • De waarde van het NotOnOrAfter-kenmerk is 70 minuten later dan de waarde van het NotBefore-kenmerk.

Doelgroep

Dit bevat een URI die een beoogde doelgroep identificeert. Microsoft Entra ID stelt de waarde van dit element in op de waarde van het AuthnRequest element dat Issuer de aanmelding heeft gestart. Als u de Audience-waarde wilt evalueren, gebruikt u de waarde van de App ID URI die is opgegeven tijdens de registratie van de toepassing.

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

Net als de Issuer waarde moet de Audience waarde exact overeenkomen met een van de service-principalnamen die de cloudservice in Microsoft Entra-id vertegenwoordigen. Als de waarde van het Issuer-element echter geen URI-waarde is, is de Audience-waarde in het antwoord de Issuer-waarde met het voorvoegsel spn:.

AttributeStatement

Dit bevat claims over het onderwerp of de gebruiker. Het volgende fragment bevat een voorbeeldelement AttributeStatement. Het beletselteken geeft aan dat het element meerdere kenmerken en kenmerkwaarden kan bevatten.

<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: de waarde van het Name-kenmerk (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) is de user-principal name van de geverifieerde gebruiker, zoals testuser@managedtenant.com.
  • ObjectIdentifier Claim : de waarde van het ObjectIdentifier kenmerk (http://schemas.microsoft.com/identity/claims/objectidentifier) is het ObjectId mapobject dat de geverifieerde gebruiker in Microsoft Entra ID vertegenwoordigt. ObjectId is een onveranderbare, wereldwijd unieke id van de geverifieerde gebruiker die veilig opnieuw kan worden gebruikt.

AuthnStatement

Dit element bevestigt dat het onderwerp van de assertie op een bepaald moment via een bepaalde methode is geverifieerd.

  • Het AuthnInstant kenmerk geeft het tijdstip aan waarop de gebruiker is geverifieerd met Microsoft Entra-id.
  • Het AuthnContext-element geeft de verificatiecontext op die wordt gebruikt om de gebruiker te verifiëren.
<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>