Protocolo SAML de logon único

Este artigo aborda as solicitações e respostas de autenticação saml 2.0 compatíveis com o Microsoft Entra ID para SSO (logon único).

O diagrama de protocolo a seguir descreve a sequência de logon único. O serviço de nuvem (o provedor de serviços) usa uma associação de Redirecionamento HTTP para passar um elemento AuthnRequest (solicitação de autenticação) para a ID do Microsoft Entra (o provedor de identidade). Em seguida, a ID do Microsoft Entra usa uma associação de postagem HTTP para postar um elemento Response no serviço de nuvem.

Nota

Este artigo discute o uso do SAML para logon único. Para obter mais informações sobre outras maneiras de lidar com o logon único (por exemplo, usando o OpenID Connect ou a autenticação integrada do Windows), consulte Logon único em aplicativos no Microsoft Entra ID.

AuthnRequest

Para solicitar uma autenticação de usuário, os serviços de nuvem enviam um elemento AuthnRequest para a ID do Microsoft Entra. Um exemplo de AuthnRequest SAML 2.0 pode ser semelhante ao exemplo a seguir:

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

Parâmetro	Tipo	Descrição
ID	Necessário	A ID do Microsoft Entra usa esse atributo para preencher o atributo InResponseTo da resposta retornada. A ID não deve começar com um número, portanto, uma estratégia comum é anexar uma cadeia de caracteres como "ID" à representação de cadeia de caracteres de um GUID. Por exemplo, id6c1c178c166d486687be4aaf5e482730 é uma ID válida.
Version	Necessário	Esse parâmetro deve ser definido como 2.0.
IssueInstant	Necessário	Esta é uma cadeia de caracteres DateTime com um valor UTC e formato de viagem de ida e volta ("o"). A ID do Microsoft Entra espera um valor DateTime desse tipo, mas não avalia nem usa o valor.
AssertionConsumerServiceURL	Opcional	Se fornecido, esse parâmetro deve corresponder ao RedirectUri do serviço de nuvem na ID do Microsoft Entra.
ForceAuthn	Opcional	Esse é um valor booliano. Se for verdade, isso significa que o usuário será forçado a autenticar novamente, mesmo que tenha uma sessão válida com a ID do Microsoft Entra.
IsPassive	Opcional	Esse é um valor booliano que especifica se a ID do Microsoft Entra deve autenticar o usuário silenciosamente, sem interação do usuário, usando o cookie de sessão, se houver. Se isso for verdade, a ID do Microsoft Entra tentará autenticar o usuário usando o cookie de sessão.

Todos os outros atributos AuthnRequest, como Consent, Destination, AssertionConsumerServiceIndex, AttributeConsumerServiceIndexe ProviderName, são ignorados.

A ID do Microsoft Entra também ignora o elemento Conditions no AuthnRequest.

Emissor

O elemento em um deve corresponder exatamente a um dos ServicePrincipalNames no serviço de nuvem na ID do Microsoft Entra. Normalmente, isso é definido como o URI da ID do aplicativo especificado durante o registro do aplicativo.

Um trecho SAML que contém o elemento Issuer se parece com o seguinte exemplo:

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

NameIDPolicy

Esse elemento solicita um formato de ID de nome específico na resposta e é opcional em AuthnRequest elementos enviados para a ID do Microsoft Entra.

Um elemento NameIdPolicy se parece com o seguinte exemplo:

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

Se NameIDPolicy for fornecido, você poderá incluir seu atributo Format opcional. O atributo Format pode ter apenas um dos seguintes valores; qualquer outro valor resulta em um erro.

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: a ID do Microsoft Entra emite a declaração NameID como um identificador a par.
• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: a ID do Microsoft Entra emite a declaração NameID no formato de endereço de email.
• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: esse valor permite que a ID do Microsoft Entra selecione o formato de declaração. A ID do Microsoft Entra emite a declaração NameID como um identificador par.
• urn:oasis:names:tc:SAML:2.0:nameid-format:transient: a ID do Microsoft Entra emite a declaração NameID como um valor gerado aleatoriamente exclusivo para a operação de SSO atual. Isso significa que o valor é temporário e não pode ser usado para identificar o usuário de autenticação.

Se SPNameQualifier for especificada, a ID do Microsoft Entra inclui o mesmo SPNameQualifier na resposta.

A ID do Microsoft Entra ignora o atributo AllowCreate.

RequestedAuthnContext

O elemento RequestedAuthnContext especifica os métodos de autenticação desejados. É opcional em AuthnRequest elementos enviados para a ID do Microsoft Entra.

Nota

Se o RequestedAuthnContext estiver incluído na solicitação SAML, o elemento Comparison deverá ser definido como exact.

A ID do Microsoft Entra dá suporte aos seguintes valores de AuthnContextClassRef.

Método de autenticação	URI da classe de contexto de autenticação
Kerberos	urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
Nome de usuário e senha	urn:oasis:names:tc:SAML:2.0:ac:classes:Password
Infraestrutura de chave pública pgp	urn:oasis:names:tc:SAML:2.0:ac:classes:PGP
Senha remota segura	urn:oasis:names:tc:SAML:2.0:ac:classes:SecureRemotePassword
Assinatura Digital XML	urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig
Infraestrutura de chave pública simples	urn:oasis:names:tc:SAML:2.0:ac:classes:SPKI
Cartão inteligente	urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard
Cartão inteligente com chave privada fechada e um PIN	urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
Cliente TLS (Transport Layer Security)	urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient
Unspecified	urn:oasis:names:tc:SAML:2.0:ac:classes:Unspecified
Certificado X.509	urn:oasis:names:tc:SAML:2.0:ac:classes:X509
Autenticação integrada do Windows	urn:federation:authentication:windows

Escopo

O elemento Scoping, que inclui uma lista de provedores de identidade, é opcional em AuthnRequest elementos enviados para a ID do Microsoft Entra.

Se fornecido, não inclua o atributo ProxyCount, IDPListOption ou elemento RequesterID, pois eles não têm suporte.

Assinatura

Um elemento Signature em elementos AuthnRequest é opcional. A ID do Microsoft Entra pode ser configurada para impor o requisito de solicitações de autenticação assinadas. Se habilitada, somente as solicitações de autenticação assinadas serão aceitas, caso contrário, a verificação do solicitante será fornecida apenas respondendo às URLs de Serviço do Consumidor de Declaração registradas.

Assunto

Não inclua um elemento Subject. A ID do Microsoft Entra não dá suporte à especificação de um assunto no AuthnRequest e retornará um erro se um for fornecido.

Em vez disso, um assunto pode ser fornecido adicionando um parâmetro login_hint à solicitação HTTP à URL de logon único, com o NameID da entidade como o valor do parâmetro.

Resposta

Quando um logon solicitado for concluído com êxito, a ID do Microsoft Entra postará uma resposta ao serviço de nuvem. Uma resposta a uma tentativa de logon bem-sucedida se parece com o seguinte exemplo:

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

Resposta

O elemento Response inclui o resultado da solicitação de autorização. A ID do Microsoft Entra define os valores ID, Version e IssueInstant no elemento Response. Ele também define os seguintes atributos:

• Destination: quando o logon é concluído com êxito, isso é definido como o RedirectUri do provedor de serviços (serviço de nuvem).
• InResponseTo: isso é definido como o atributo ID do elemento AuthnRequest que iniciou a resposta.

Emissor

A ID do Microsoft Entra define o elemento Issuer para https://sts.windows.net/<TenantIDGUID>/ em que <TenantIDGUID> é a ID do locatário do Microsoft Entra.

Por exemplo, uma resposta com o elemento Issuer pode ser semelhante ao seguinte exemplo:

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

Estado

O elemento Status transmite o êxito ou a falha do logon. Ele inclui o elemento StatusCode, que contém um código ou um conjunto de códigos aninhados que representa o status da solicitação. Ele também inclui o elemento StatusMessage, que contém mensagens de erro personalizadas geradas durante o processo de logon.

O exemplo a seguir é uma resposta SAML a uma tentativa de logon malsucedida.

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

Asserção

Além do ID, IssueInstant e Version, a ID do Microsoft Entra define os seguintes elementos no elemento Assertion da resposta.

Emissor

Isso é definido como https://sts.windows.net/<TenantIDGUID>/em que <TenantIDGUID> é a ID do locatário do Microsoft Entra.

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

Assinatura

A ID do Microsoft Entra assina a declaração em resposta a um logon bem-sucedido. O elemento Signature contém uma assinatura digital que o serviço de nuvem pode usar para autenticar a origem para verificar a integridade da declaração.

Para gerar essa assinatura digital, a ID do Microsoft Entra usa a chave de assinatura no elemento IDPSSODescriptor de seu documento de metadados.

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

Assunto

Isso especifica o princípio que é o assunto das instruções na declaração. Ele contém um elemento NameID, que representa o usuário autenticado. O valor NameID é um identificador direcionado que é direcionado apenas para o provedor de serviços que é o público-alvo do token. É persistente - pode ser revogado, mas nunca é reatribuído. Também é opaco, pois não revela nada sobre o usuário e não pode ser usado como um identificador para consultas de atributo.

O atributo Method do elemento SubjectConfirmation é sempre definido como 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>

Condições

Esse elemento especifica condições que definem o uso aceitável de declarações 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>

Os atributos NotBefore e NotOnOrAfter especificam o intervalo durante o qual a asserção é válida.

• O valor do atributo NotBefore é igual ou ligeiramente (menos de um segundo) posterior ao valor de IssueInstant atributo do elemento Assertion. A ID do Microsoft Entra não conta com nenhuma diferença de tempo entre si e o serviço de nuvem (provedor de serviços) e não adiciona nenhum buffer a esse momento.
• O valor do atributo NotOnOrAfter é 70 minutos depois do valor do atributo NotBefore.

Público

Isso contém um URI que identifica um público-alvo pretendido. A ID do Microsoft Entra define o valor desse elemento como o valor de Issuer elemento do AuthnRequest que iniciou o logon. Para avaliar o valor Audience, use o valor do App ID URI especificado durante o registro do aplicativo.

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

Assim como o valor Issuer, o valor Audience deve corresponder exatamente a um dos nomes da entidade de serviço que representa o serviço de nuvem na ID do Microsoft Entra. No entanto, se o valor do elemento Issuer não for um valor de URI, o valor Audience na resposta será o valor Issuer prefixado com spn:.

AttributeStatement

Isso contém declarações sobre o assunto ou o usuário. O trecho a seguir contém um elemento AttributeStatement de exemplo. As reticências indicam que o elemento pode incluir vários atributos e valores de atributo.

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

• de Declaração de Nome – O valor do atributo Name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) é o nome principal do usuário autenticado, como testuser@managedtenant.com.
• objectIdentifier Claim - O valor do atributo ObjectIdentifier (http://schemas.microsoft.com/identity/claims/objectidentifier) é o ObjectId do objeto de diretório que representa o usuário autenticado na ID do Microsoft Entra. ObjectId é um identificador seguro imutável, globalmente exclusivo e reutilizado do usuário autenticado.

AuthnStatement

Esse elemento afirma que o assunto de asserção foi autenticado por um determinado meio em um determinado momento.

• O atributo AuthnInstant especifica a hora em que o usuário foi autenticado com a ID do Microsoft Entra.
• O elemento AuthnContext especifica o contexto de autenticação usado para autenticar o usuário.

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