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) 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.
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="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 |
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 deNameIDclaim uit als een paargewijze id.urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: Microsoft Entra ID geeft deNameIDclaim 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 deNameIDclaim uit als een paargewijze id.urn:oasis:names:tc:SAML:2.0:nameid-format:transient: Microsoft Entra ID geeft deNameIDclaim 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="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>
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 deRedirectUriserviceprovider (cloudservice).InResponseTo: dit is ingesteld op hetID-kenmerk van hetAuthnRequest-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-dd22-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 hetIssueInstant-kenmerk van hetAssertion-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 hetNotBefore-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, zoalstestuser@managedtenant.com. - ObjectIdentifier Claim : de waarde van het
ObjectIdentifierkenmerk (http://schemas.microsoft.com/identity/claims/objectidentifier) is hetObjectIdmapobject dat de geverifieerde gebruiker in Microsoft Entra ID vertegenwoordigt.ObjectIdis 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
AuthnInstantkenmerk 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>