Credenciais de certificado de autenticação do aplicativo da plataforma de identidade da Microsoft

  • Artigo

A plataforma de identidade da Microsoft permite que um aplicativo use suas próprias credenciais para autenticação em qualquer lugar em que um segredo do cliente possa ser usado, por exemplo, no fluxo de concessão de credenciais do cliente OAuth 2.0 e no fluxo OBO (em nome de).

Uma forma de credencial que um aplicativo pode usar para autenticação é uma declaração JSON Web Token (JWT) assinada com um certificado que o aplicativo possui. Isso é descrito na especificação do OpenID Connect para a opção de autenticação de cliente private_key_jwt.

Se você estiver interessado em usar um JWT emitido por outro provedor de identidade como uma credencial para seu aplicativo, confira a federação de identidade da carga de trabalho para saber como configurar uma política de federação.

Formato de asserção

Para computar a asserção, você pode usar uma das várias bibliotecas JWT no idioma de sua escolha - MSAL dá suporte a isso usando .WithCertificate(). As informações são transportadas pelo token em seu Título, Declarações e Assinatura.

Parâmetro Comentário
alg Deve ser RS256
typ Deve ser JWT
x5t Impressão digital SHA-1 codificada em Base64url da codificação DER do certificado X. 509. Por exemplo, considerando um hash de certificado X.509 de 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hex), a declaração x5t seria hOBcHZi846VCHSJbFAs26Go9VTQ (Base64url).

Declarações (carga)

Tipo de declaração Valor Descrição
aud https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token A declaração "aud" (audience) identifica os destinatários para os quais o JWT se destina (aqui, a ID do Microsoft Entra). Confira a RFC 7519, Seção 4.1.3. Nesse caso, esse destinatário é o servidor de logon (login.microsoftonline.com).
exp 1601519414 A declaração "exp" (hora de expiração) identifica a hora de expiração ou a hora após ela na qual o JWT não deve ser aceito para processamento. Confira a RFC 7519, Seção 4.1.4. Isso permite que a asserção seja usada até lá, portanto, mantenha-a curta, de 5 a 10 minutos após nbf no máximo. O Microsoft Entra ID não impõe restrições ao tempo exp atualmente.
iss {ClientID} A declaração "iss" (issuer) identifica a entidade de segurança que emitiu o JWT, neste caso, o aplicativo cliente. Use a ID do aplicativo GUID.
jti (um Guid) a declaração "jti" (ID do JWT) fornece um identificador exclusivo para o JWT. O valor do identificador deve ser atribuído de forma a garantir que haja uma probabilidade insignificante de que o mesmo valor seja acidentalmente atribuído a um objeto de dados diferente; se o aplicativo usar vários emissores, as colisões DEVEM ser evitadas entre os valores produzidos por diferentes emissores também. O valor "jti" é uma cadeia de caracteres que diferencia maiúsculas de minúsculas. RFC 7519, Seção 4.1.7
nbf 1601519114 A declaração "nbf" (não antes) identifica a hora antes da qual o JWT NÃO DEVE ser aceito para processamento. RFC 7519, Seção 4.1.5. O uso da hora atual é apropriado.
sub {ClientID} A declaração "sub" (subject) identifica o assunto do JWT, neste caso, também seu aplicativo. Use o mesmo valor que iss.
iat 1601519114 a declaração "iat" (emitido em) identifica a hora em que o JWT foi emitido. Essa declaração pode ser usada para determinar a idade do JWT. RFC 7519, Seção 4.1.5.

Assinatura

A assinatura é calculada aplicando o certificado conforme descrito na especificação Token Web JSON RFC7519.

Exemplo de uma declaração JWT decodificada

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

Exemplo de uma declaração JWT codificada

A cadeia de caracteres a seguir é um exemplo de asserção codificado. Se você olhar com cuidado, você notará três seções separadas por pontos (.):

  • A primeira seção codifica o cabeçalho
  • A segunda seção codifica as declarações (carga)
  • A última seção é a assinatura computada com os certificados do conteúdo das duas primeiras seções
"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Registrar o certificado na plataforma de identidade da Microsoft

Você pode associar a credencial de certificado ao aplicativo cliente na plataforma de identidade da Microsoft por meio do centro de administração do Microsoft Entra usando qualquer um dos métodos a seguir:

Fazendo upload do arquivo de certificado

Na guia Registros de aplicativo do aplicativo cliente:

  1. Selecione Certificados e Segredos>Certificados.
  2. Selecione Carregar certificado e selecione o arquivo de certificado a ser carregado.
  3. Selecione Adicionar. Após o carregamento do certificado, os valores de impressão digital, data de início e expiração são exibidos.

Atualizando o manifesto do aplicativo

Depois de adquirir um certificado, calcule estes valores:

  • $base64Thumbprint - Valor codificado em Base64 do hash de certificado
  • $base64Value - Valor codificado em Base64 dos dados brutos de certificado

Forneça um GUID para identificar a chave no manifesto do aplicativo ($keyId).

No registro do aplicativo do Azure para o aplicativo cliente:

  1. Selecione Manifesto para abrir o manifesto do aplicativo.

  2. Substitua a propriedade keyCredentials pelas novas informações de certificado usando o esquema a seguir.

    "keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

  3. Salve as edições no manifesto do aplicativo e, em seguida, carregue-o na plataforma de identidade da Microsoft.

    A propriedade keyCredentials tem vários valores, portanto, você pode fazer upload de vários certificados para um gerenciamento de chaves mais sofisticado.

Usar uma declaração de cliente

As declarações de cliente podem ser usadas em qualquer lugar em que um segredo do cliente seria usado. Por exemplo, no fluxo de código de autorização, passe em um client_secret para provar que a solicitação é proveniente de seu aplicativo. Você pode substituir isso pelos parâmetros client_assertion e client_assertion_type.

Parâmetro Valor Descrição
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer Esse é um valor fixo, indicando que você está usando uma credencial de certificado.
client_assertion JWT Esse é o JWT criado acima.

Próximas etapas

A biblioteca MSAL.NET lida com esse cenário em uma única linha de código.

O exemplo de código Aplicativo de console do daemon do .NET usando a plataforma de identidade da Microsoft em GitHub mostra como um aplicativo usa as próprias credenciais para autenticação. Também mostra como você pode criar um certificado autoassinado usando o cmdlet New-SelfSignedCertificate PowerShell. Você também pode usar os scripts de criação do aplicativo no repositório de exemplo para criar os certificados, calcular a impressão digital e assim por diante.