Afirmações confidenciais do cliente

Para provar a sua identidade, as aplicações cliente confidenciais trocam um segredo com o Microsoft Entra ID. O segredo pode ser:

• Um segredo do cliente (palavra-passe da aplicação).
• Um certificado, que é usado para construir uma asserção assinada contendo reivindicações padrão.

Este segredo pode também ser uma afirmação assinada diretamente.

O MSAL.NET tem quatro métodos para fornecer credenciais ou asserções à aplicação cliente confidencial:

• .WithClientSecret()
• .WithCertificate()
• .WithClientAssertion()
• .WithClientClaims()

Alegações do cliente

Isto é útil se quiser tratar do certificado sozinho. Por exemplo, se quiser usar as APIs do Azure KeyVault para assinar, o que elimina a necessidade de descarregar os certificados. Uma asserção de cliente assinada assume a forma de um JWT assinado com o payload contendo as reivindicações de autenticação exigidas pelo Microsoft Entra ID, codificado em Base64. Ou pode ser um JWT de outro fornecedor de identidade, no cenário "Credencial de Identidade Federada".

Use o delegado, que lhe permite calcular a asserção sempre que a MSAL precisa de obter um novo token do fornecedor de identidade. O MSAL não invoca o seu delegado se for encontrado um token na cache.

string signedClientAssertion = GetOrComputeAssertion();
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithClientAssertion(async (AssertionRequestOptions options) => {
                                            // use 'options.ClientID' or 'options.TokenEndpoint' to generate client assertion
                                            return await GetClientAssertionAsync(options.ClientID, options.TokenEndpoint, options.CancellationToken); 
                                          })
                                          .Build();

As alegações esperadas pela Microsoft Entra ID na declaração assinada são:

Se usar um certificado como secreto do cliente, o certificado deve ser implementado em segurança. Recomendamos que armazene o certificado num local seguro suportado pela plataforma, como na loja de certificados no Windows ou utilizando o Azure Key Vault.

Elaboração da afirmação

Este é um exemplo que utiliza Microsoft.IdentityModel.JsonWebTokens para criar a asserção.

        string GetSignedClientAssertion(X509Certificate2 certificate, string tenantId, string clientId)
        {                            
            // no need to add exp, nbf as JsonWebTokenHandler will add them by default.
            var claims = new Dictionary<string, object>()
            {
                { "aud", tokenEndpoint },
                { "iss", clientId },
                { "jti", Guid.NewGuid().ToString() },
                { "sub", clientId }
            };

            var securityTokenDescriptor = new SecurityTokenDescriptor
            {
                Claims = claims,
                SigningCredentials = new X509SigningCredentials(certificate)
            };

            var handler = new JsonWebTokenHandler();
            var signedClientAssertion = handler.CreateToken(securityTokenDescriptor);
        }

Alternativamente, se não quiser usar a Microsoft. IdentityModel.JsonWebTokens:

static string Base64UrlEncode(byte[] arg)
{
    char Base64PadCharacter = '=';
    char Base64Character62 = '+';
    char Base64Character63 = '/';
    char Base64UrlCharacter62 = '-';
    char Base64UrlCharacter63 = '_';

    string s = Convert.ToBase64String(arg);
    s = s.Split(Base64PadCharacter)[0]; // RemoveAccount any trailing padding
    s = s.Replace(Base64Character62, Base64UrlCharacter62); // 62nd char of encoding
    s = s.Replace(Base64Character63, Base64UrlCharacter63); // 63rd char of encoding

    return s;
}

static string GetSignedClientAssertion(X509Certificate2 certificate, string tenantId, string clientId)
{
    // Get the RSA with the private key, used for signing.
    var rsa = certificate.GetRSAPrivateKey();

    //alg represents the desired signing algorithm, which is SHA-256 in this case
    //x5t represents the certificate thumbprint base64 url encoded
    var header = new Dictionary<string, string>()
    {
        { "alg", "PS256"},
        { "typ", "JWT" },
        { "x5t#S256", Base64UrlHelpers.Encode(certificate.GetCertHash(HashAlgorithmName.SHA256))},
    };

    //Please see the previous code snippet on how to craft claims for the GetClaims() method
    var claims = GetClaims(tenantId, clientId);

    var headerBytes = JsonSerializer.SerializeToUtf8Bytes(header);
    var claimsBytes = JsonSerializer.SerializeToUtf8Bytes(claims);
    string token = Base64UrlEncode(headerBytes) + "." + Base64UrlEncode(claimsBytes);

    string signature = Base64UrlEncode(rsa.SignData(Encoding.UTF8.GetBytes(token), HashAlgorithmName.SHA256, RSASignaturePadding.Pss));
    string signedClientAssertion = string.Concat(token, ".", signature);
    return signedClientAssertion;
}

WithClientClaims

Em alguns casos, os programadores querem injetar algumas reivindicações nas asserções, mas gostariam que a MSAL tratasse da criação da asserção e da assinatura.

WithClientClaims(X509Certificate2 certificate, IDictionary<string, string> claimsToSign, bool mergeWithDefaultClaims = true) produz uma asserção assinada que contém as declarações esperadas pelo Microsoft Entra ID, além de declarações adicionais do cliente que pretende enviar.

string ipAddress = "192.168.1.2";
X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithAuthority(new Uri(config.Authority))
                                          .WithClientClaims(certificate, 
                                                                      new Dictionary<string, string> { { "client_ip", ipAddress } })
                                          .Build();

Se uma das declarações no dicionário que transmite corresponder a uma das declarações obrigatórias, o valor da declaração adicional é tido em consideração. Sobrepõe-se às reivindicações calculadas pelo MSAL.NET.

Se quiser fornecer as suas próprias declarações, incluindo as declarações obrigatórias esperadas pelo Microsoft Entra ID, passe false para o parâmetro mergeWithDefaultClaims.