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

Artigo
04/10/2024

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 PS256
`typ`	Deve ser JWT
`x5t#s256`	Impressão digital SHA-256 codificada em Base64url da codificação DER do certificado X.509.

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. Use o preenchimento PSS.

Exemplo de uma asserção JWT decodificada

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t#sha256": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
.
{
  "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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
}
.
"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:

Selecione Certificados & certificados secretos>.
Selecione Carregar certificado e selecione o arquivo de certificado a ser carregado.
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:

Selecione Manifesto para abrir o manifesto do aplicativo.

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"
    }
]

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.

Partilhar via