Credenciais do certificado de autenticação de 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 onde um segredo de cliente possa ser usado, por exemplo, no fluxo de concessão de credenciais de cliente OAuth 2.0 e no fluxo em nome de (OBO).

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

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

Formato da asserção

Para calcular a afirmação, você pode usar uma das muitas bibliotecas JWT no idioma de sua escolha - o MSAL suporta isso usando .WithCertificate(). As informações são carregadas pelo token em seu cabeçalho, declarações e assinatura.

Parâmetro Observação
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, se indicar um hash de certificado X.509 de 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (hexadecimal), a afirmação x5t será hOBcHZi846VCHSJbFAs26Go9VTQ (Base64url).

Sinistros (carga útil)

Tipo de afirmação valor Description
aud https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token A declaração "aud" (audiência) identifica os destinatários aos quais o JWT se destina (aqui Microsoft Entra ID) Consulte RFC 7519, Seção 4.1.3. Nesse caso, esse destinatário é o servidor de login (login.microsoftonline.com).
exp 1601519414 A reivindicação "exp" (tempo de expiração) identifica o tempo de expiração no qual ou após o qual o JWT não deve ser aceito para processamento. Ver RFC 7519, Secção 4.1.4. Isso permite que a asserção seja usada até lá, então mantenha-a curta - 5-10 minutos depois nbf no máximo. O Microsoft Entra ID não impõe restrições de exp tempo atualmente.
iss {ID do cliente} A declaração "iss" (emissor) identifica o principal que emitiu o JWT, neste caso o seu pedido cliente. Use o ID do aplicativo GUID.
jti (um Guid) A declaração "jti" (JWT ID) fornece um identificador exclusivo para o JWT. O valor do identificador deve ser atribuído de forma a garantir que há uma probabilidade insignificante de que o mesmo valor seja atribuído acidentalmente a um objeto de dados diferente, se o aplicativo usar vários emissores, colisões DEVEM ser evitadas entre 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 reivindicação "nbf" (não antes) identifica o tempo antes do qual o JWT NÃO DEVE ser aceito para processamento. RFC 7519, Secção 4.1.5. Usar a hora atual é apropriado.
sub {ID do cliente} A reivindicação "sub" (sujeito) identifica o sujeito do JWT, neste caso também o seu pedido. Use o mesmo valor que iss.
iat 1601519114 A declaração "iat" (emitida em) identifica o momento em que o JWT foi emitido. Esta afirmação pode ser usada para determinar a idade do JWT. RFC 7519, Secção 4.1.5.

Assinatura

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

Exemplo de uma asserçã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 asserção JWT codificada

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

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

Registe o seu certificado com a plataforma de identidade 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 seguintes métodos:

Carregando o arquivo de certificado

Na guia Registros de aplicativo para o aplicativo cliente:

  1. Selecione Certificados & certificados secretos>.
  2. Selecione Carregar certificado e selecione o arquivo de certificado a ser carregado.
  3. Selecione Adicionar. Depois que o certificado é carregado, a impressão digital, a data de início e os valores de expiração são exibidos.

Atualizando o manifesto do aplicativo

Depois de adquirir um certificado, calcule estes valores:

  • $base64Thumbprint – valor com codificação Base64 do hash do certificado
  • $base64Value - Valor codificado em Base64 dos dados brutos do 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 do 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 carregue o manifesto na plataforma de identidade da Microsoft.

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

Usando uma asserção de cliente

As asserções do cliente podem ser usadas em qualquer lugar onde um segredo do cliente seria usado. Por exemplo, no fluxo de código de autorização, você pode passar um client_secret para provar que a solicitação está vindo do seu aplicativo. Você pode substituir isso por client_assertion e client_assertion_type parâmetros.

Parâmetro valor Description
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 Este é o JWT criado acima.

Próximos passos

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

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