SAML-protocol voor eenmalige aanmelding

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) gebruikt een HTTP-omleidingsbinding om een element AuthnRequest (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 naar de cloudservice.

Notitie

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

AuthnRequest

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

<samlp:AuthnRequest
  xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
  ID="C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w"
  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	Facultatief	Indien opgegeven, moet deze parameter overeenkomen met de RedirectUri van de cloudservice in Microsoft Entra ID.
ForceAuthn	Facultatief	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	Facultatief	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, AttributeConsumerServiceIndexen ProviderName worden genegeerd.

Microsoft Entra ID negeert ook het Conditions element in AuthnRequest.

Uitgevende instelling

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 element Issuer ziet er als volgt uit:

<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 er als volgt uit:

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

Als NameIDPolicy is opgegeven, kunt u het optionele Format kenmerk opnemen. Het kenmerk Format mag 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 is opgegeven, bevat de Microsoft Entra-id dezelfde SPNameQualifier in het antwoord.

Microsoft Entra ID negeert het kenmerk AllowCreate.

RequestedAuthnContext

Het element RequestedAuthnContext geeft de gewenste verificatiemethoden op. Dit is optioneel in AuthnRequest elementen die naar Microsoft Entra-id worden verzonden.

Notitie

Als de RequestedAuthnContext is opgenomen in de SAML-aanvraag, moet het Comparison element worden ingesteld op exact.

Microsoft Entra ID biedt ondersteuning voor het volgen van AuthnContextClassRef waarden.

Verificatiemethode	URI van verificatiecontextklasse
Kerberos	urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
Gebruikersnaam en wachtwoord	urn:oasis:names:tc:SAML:2.0:ac:classes:Password
Openbare PGP-sleutelinfrastructuur	urn:oasis:names:tc:SAML:2.0:ac:classes:PGP
Extern wachtwoord beveiligen	urn:oasis:names:tc:SAML:2.0:ac:classes:SecureRemotePassword
DIGITALE XML-handtekening	urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig
Eenvoudige openbare-sleutelinfrastructuur	urn:oasis:names:tc:SAML:2.0:ac:classes:SPKI
Smartcard	urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard
Smartcard met ingesloten persoonlijke sleutel en pincode	urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
TLS-client (Transport Layer Security)	urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient
Onbepaald	urn:oasis:names:tc:SAML:2.0:ac:classes:Unspecified
X.509-certificaat	urn:oasis:names:tc:SAML:2.0:ac:classes:X509
Geïntegreerde Windows-verificatie	urn:federation:authentication:windows

Scoping

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, moet u het kenmerk ProxyCount, IDPListOption of RequesterID element niet opnemen, omdat deze niet worden ondersteund.

Handtekening

Een Signature element in 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 HTTP-aanvraag aan de URL voor eenmalige aanmelding, waarbij de NameID van het onderwerp de parameterwaarde is.

Antwoord

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="C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w" 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>

Antwoord

Het element Response bevat het resultaat van de autorisatieaanvraag. Microsoft Entra-id stelt de ID, Version en IssueInstant waarden in het Response-element in. Ook worden de volgende kenmerken ingesteld:

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

Uitgevende instelling

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

Een antwoord met het element Issuer 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 element Status geeft het succes of falen van de aanmelding aan. Het bevat het StatusCode-element, dat een code of een set geneste codes bevat die de status van de aanvraag vertegenwoordigt. Het bevat ook het StatusMessage-element, dat aangepaste foutberichten bevat 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-dd22-eeeeee333333
    Timestamp: 2013-03-18 08:49:24Z</samlp:StatusMessage>
    </samlp:Status>
</samlp:Response>

Bewering

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

Uitgevende instelling

Dit is ingesteld op https://sts.windows.net/<TenantIDGUID>/waarbij <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 element Signature bevat een digitale handtekening die de cloudservice kan gebruiken om de bron te verifiëren om de integriteit van de assertie te verifiëren.

Voor het genereren van deze digitale handtekening gebruikt Microsoft Entra ID de ondertekeningssleutel in het IDPSSODescriptor element van het 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 vertegenwoordigt. De NameID waarde is een doel-id die alleen wordt doorgestuurd naar de serviceprovider die de doelgroep voor het token is. Het is permanent. Het kan worden ingetrokken, maar wordt nooit opnieuw toegewezen. Het is ook ondoorzichtig, omdat er niets over de gebruiker wordt weergegeven en niet kan worden gebruikt als id voor kenmerkquery's.

Het kenmerk Method van het element SubjectConfirmation 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>

De kenmerken NotBefore en NotOnOrAfter geven het interval op waarin de assertie geldig is.

• De waarde van het kenmerk NotBefore is gelijk aan of iets (minder dan een seconde) later dan de waarde van 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 kenmerk NotOnOrAfter is 70 minuten later dan de waarde van het kenmerk NotBefore.

Audiëntie

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

<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 voorafgegaan door spn:.

AttributeStatement

Dit bevat claims over het onderwerp of de gebruiker. Het volgende fragment bevat een voorbeeld AttributeStatement element. 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 kenmerk Name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) is de principal-naam van de gebruiker van de geverifieerde gebruiker, zoals testuser@managedtenant.com.
• ObjectIdentifier Claim : de waarde van het kenmerk ObjectIdentifier (http://schemas.microsoft.com/identity/claims/objectidentifier) is de ObjectId van het mapobject dat de geverifieerde gebruiker in Microsoft Entra-id vertegenwoordigt. ObjectId is een onveranderbare, wereldwijd unieke en hergebruik veilige id van de geverifieerde gebruiker.

AuthnStatement

Dit element bevestigt dat het assertieonderwerp op een bepaald moment is geverifieerd met een bepaalde middelen.

• Het kenmerk AuthnInstant geeft het tijdstip aan waarop de gebruiker is geverifieerd met Microsoft Entra-id.
• Het element AuthnContext 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>