Протокол единого входа SAML

Статья
04/08/2024

В этой статье рассматриваются запросы и ответы проверки подлинности SAML 2.0, поддерживаемые идентификатором Microsoft Entra для единого входа.

На следующей схеме протокола описывается последовательность единого входа. Облачная служба (поставщик служб) использует привязку ПЕРЕНАПРАВЛЕНия HTTP для передачи AuthnRequest элемента (запроса проверки подлинности) идентификатору Microsoft Entra (поставщику удостоверений). Затем идентификатор Microsoft Entra использует привязку записи HTTP для публикации Response элемента в облачную службу.

Снимок экрана: рабочий процесс единого входа.

Примечание.

В этой статье рассматривается использование SAML для единого входа. Дополнительные сведения о других способах обработки единого входа (например, с помощью OpenID Подключение или интегрированной проверка подлинности Windows) см. в статье "Единый вход в приложения" в идентификаторе Microsoft Entra.

AuthnRequest

Чтобы запросить проверку подлинности пользователя, облачные службы отправляют AuthnRequest элемент в идентификатор Microsoft Entra. Пример SAML 2.0 AuthnRequest должен выглядеть примерно так:

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

Параметр	Тип	Описание
`ID`	Обязательное поле	Идентификатор Microsoft Entra использует этот атрибут для заполнения `InResponseTo` атрибута возвращаемого ответа. Идентификатор не должен начинаться с цифры, поэтому общая стратегия предусматривает добавление такой строки, как ID, в начало строкового представления GUID. Например, `id6c1c178c166d486687be4aaf5e482730` — допустимый идентификатор.
`Version`	Обязательное поле	Этот параметр должен иметь значение `2.0`.
`IssueInstant`	Обязательное поле	Это строка DateTime со значением в формате всемирного времени (UTC) и с преобразованием без потери данных ("o"). Идентификатор Microsoft Entra ожидает значение DateTime этого типа, но не оценивает или не использует значение.
`AssertionConsumerServiceURL`	Необязательно	Если этот параметр указан, этот параметр должен соответствовать `RedirectUri` облачной службе в идентификаторе Microsoft Entra ID.
`ForceAuthn`	Необязательно	Это логическое значение. Если значение true, это означает, что пользователь будет вынужден повторно пройти проверку подлинности, даже если у него есть действительный сеанс с идентификатором Microsoft Entra.
`IsPassive`	Необязательно	Это логическое значение, указывающее, должен ли идентификатор Microsoft Entra автоматически проходить проверку подлинности пользователя без взаимодействия с пользователем, используя файл cookie сеанса, если он существует. Если это верно, идентификатор Microsoft Entra пытается пройти проверку подлинности пользователя с помощью файла cookie сеанса.

Все остальные AuthnRequest атрибуты, такие как Consent, Destination, AttributeConsumerServiceIndexAssertionConsumerServiceIndexи ProviderName игнорируются.

Идентификатор Microsoft Entra также игнорирует Conditions элемент в AuthnRequest.

Издатель

Элемент Issuer в объекте AuthnRequest должен точно соответствовать одному из servicePrincipalNames в облачной службе в идентификаторе Microsoft Entra. Обычно здесь передается URI идентификатора приложения , указанный во время регистрации приложения.

Фрагмент SAML, в котором содержится элемент Issuer, выглядит так:

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

NameIDPolicy

Этот элемент запрашивает определенный формат идентификатора имени в ответе и является необязательным в AuthnRequest элементах, отправляемых в идентификатор Microsoft Entra.

Элемент NameIdPolicy выглядит так:

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

Если элемент NameIDPolicy указан, можно включить его необязательный атрибут Format. У атрибута Format может быть только одно из следующих значений, так как любое другое значение приводит к ошибке.

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: идентификатор Microsoft Entra выдает NameID утверждение в качестве парного идентификатора.
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: идентификатор Microsoft Entra выдает NameID утверждение в формате адреса электронной почты.
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: это значение позволяет идентификатору Microsoft Entra выбрать формат утверждения. Идентификатор Microsoft Entra выдает NameID утверждение в качестве парного идентификатора.
urn:oasis:names:tc:SAML:2.0:nameid-format:transient: идентификатор Microsoft Entra выдает NameID утверждение как случайно созданное значение, уникальное для текущей операции единого входа. Это означает, что значение является временным и не может использоваться для идентификации пользователя, проверяющего подлинность.

Если SPNameQualifier задано, идентификатор Microsoft Entra содержит то же SPNameQualifier самое в ответе.

Идентификатор Microsoft Entra игнорирует AllowCreate атрибут.

RequestedAuthnContext

Элемент RequestedAuthnContext указывает нужные методы проверки подлинности. Это необязательно в элементах, отправляемых в AuthnRequest идентификатор Microsoft Entra. Идентификатор Microsoft Entra поддерживает AuthnContextClassRef такие значения, как urn:oasis:names:tc:SAML:2.0:ac:classes:Password.

Scoping

Элемент Scoping , включающий список поставщиков удостоверений, является необязательным в AuthnRequest элементах, отправленных в идентификатор Microsoft Entra.

Если он указан, не включайте атрибут ProxyCount, а также элемент IDPListOption или RequesterID, так как они не поддерживаются.

Подпись

Элемент Signature в элементах AuthnRequest не является обязательным. Microsoft Entra ID можно настроить для принудительного применения требования подписанных запросов проверки подлинности. Если этот параметр включен, принимаются только подписанные запросы проверки подлинности, в противном случае проверка отправителя осуществляется путем отправки ответа только на зарегистрированные URL-адреса службы обработчика утверждений.

Тема

Не включайте элемент Subject. Идентификатор Microsoft Entra не поддерживает указание темы и AuthnRequest возвращает ошибку, если она указана.

Вместо этого субъект можно указать, добавив параметр login_hint в HTTP-запрос к URL-адресу единого входа с идентификатором NameID субъекта в качестве значения параметра.

Response

После успешного завершения запрошенного входа идентификатор Microsoft Entra публикует ответ на облачную службу. Ответ на успешную попытку входа может выглядеть следующим образом:

<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

Элемент Response включает результат запроса на авторизацию. Идентификатор Microsoft Entra задает IDVersion значения и IssueInstant значения в элементеResponse. Он также задает следующие атрибуты:

Destination: при успешном выполнении входа оно устанавливается RedirectUri поставщиком услуг (облачной службой).
InResponseTo. Для этого атрибута задается значение ID элемента AuthnRequest, инициировавшего ответ.

Издатель

Идентификатор Microsoft Entra задает Issuer элемент https://sts.windows.net/<TenantIDGUID>/ , в котором <TenantIDGUID> находится идентификатор клиента клиента Microsoft Entra.

Например, ответ с элементом Issuer может выглядеть следующим образом:

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

Состояние

Элемент Status передает сведения об успешной или неудачной попытке входа. Он включает элемент StatusCode, содержащий код или набор блоков вложенного кода, который представляет состояние запроса. Он также включает элемент StatusMessage , содержащий настраиваемые сообщения об ошибках, создаваемые во время входа.

Ниже приведен пример ответа SAML на неудачную попытку входа.

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

Assertion

IDVersionIssueInstant Помимо идентификатора и идентификатора Microsoft Entra задает следующие элементы в Assertion элементе ответа.

Издатель

Для этого задан https://sts.windows.net/<TenantIDGUID>/<TenantIDGUID> идентификатор клиента клиента Microsoft Entra.

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

Подпись

Идентификатор Microsoft Entra подписывает утверждение в ответ на успешный вход. В элементе Signature содержится цифровая подпись, которую может использовать облачная служба для проверки подлинности источника, чтобы проверять целостность утверждения.

Для создания этой цифровой подписи идентификатор Microsoft Entra использует ключ подписи в элементе IDPSSODescriptor документа метаданных.

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

Тема

Указывает принцип, который является субъектом операторов в утверждении. Он содержит элемент NameID, который представляет пользователя, прошедшего аутентификацию. Значение NameID — целевой идентификатор, направляемый только поставщику услуг, который является аудиторией маркера. Оно носит постоянный характер. Это значение можно отменить, но нельзя переназначить. Оно также непрозрачно, так как не раскрывает никаких сведений о пользователе и его нельзя использовать в качестве идентификатора для запросов на атрибуты.

Для атрибута Method элемента SubjectConfirmation всегда задано значение 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>

Условия

Этот элемент указывает условия, определяющие приемлемое использование утверждений 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>

Атрибуты NotBefore и NotOnOrAfter указывают интервал, в течение которого утверждение допустимо.

Значение атрибута NotBefore равно значению атрибута IssueInstant в элементе Assertion или немного больше (менее чем на секунду). Идентификатор Microsoft Entra не учитывает никакой разницы между собой и облачной службой (поставщиком услуг) и не добавляет буфер в это время.
Значение атрибута NotOnOrAfter на 70 минут больше, чем значение атрибута NotBefore.

Аудитория

Он содержит код URI, который определяет предполагаемую аудиторию. Идентификатор Microsoft Entra задает значение этого элемента значением Issuer элемента, AuthnRequest инициируемого входом. Чтобы оценить значение Audience, используйте значение App ID URI, указанное при регистрации приложения.

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

Issuer Как и значение, Audience значение должно точно соответствовать одному из имен субъектов-служб, представляющих облачную службу в идентификаторе Microsoft Entra ID. Но если значения элемента Issuer и URI отличаются, значение Audience в ответе — это Issuer с префиксом spn:.

AttributeStatement

В этом элементе содержатся утверждения о субъекте или пользователе. В следующем фрагменте приведен пример элемента AttributeStatement . Многоточие указывает, что в элементе могут содержаться несколько атрибутов и их значений.

<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.com.
Утверждение ObjectIdentifier— значение ObjectIdentifier атрибута (http://schemas.microsoft.com/identity/claims/objectidentifier) является ObjectId объектом каталога, который представляет прошедшего проверку подлинности пользователя в идентификаторе Microsoft Entra. Значение ObjectId неизменяемое, глобально уникальное и повторно использует безопасный идентификатор пользователя, прошедшего проверку подлинности.

AuthnStatement

Этот элемент служит утверждением того, что проверка подлинности субъекта утверждения выполнена определенным средством в определенное время.

Атрибут AuthnInstant указывает время, в течение которого пользователь прошел проверку подлинности с помощью идентификатора Microsoft Entra.
Элемент AuthnContext указывает контекст аутентификации, использованный для аутентификации пользователя.

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

Протокол единого входа SAML

AuthnRequest

Издатель

NameIDPolicy

RequestedAuthnContext

Scoping

Подпись

Тема

Response

Response

Издатель

Состояние

Assertion

Издатель

Подпись

Тема

Условия

Аудитория

AttributeStatement

AuthnStatement

Дополнительные ресурсы