Declarações confidenciais do cliente

Para provar sua identidade, os aplicativos cliente confidenciais trocam um segredo com Microsoft Entra ID. O segredo pode ser:

• Um segredo do cliente (senha do aplicativo).
• Um certificado, que é usado para criar uma declaração assinada contendo declarações padrão.

Esse segredo também pode ser uma declaração assinada diretamente.

MSAL.NET tem quatro métodos para fornecer credenciais ou declarações ao aplicativo cliente confidencial:

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

Declarações de cliente

Isso é útil se você quiser manipular o certificado por conta própria. Por exemplo, se você quiser usar as APIs do Azure Key Vault para assinar, o que elimina a necessidade de baixar os certificados. Uma declaração de cliente assinada assume a forma de um JWT assinado com o conteúdo que contém as declarações de autenticação necessárias exigidas pelo Microsoft Entra ID, codificado em Base64. Ou pode ser um JWT emitido por um provedor de identidade diferente, no cenário de "Credencial de Identidade Federada".

Use o delegado, que permite calcular a asserção sempre que a MSAL precisar obter um novo token do provedor de identidade. A MSAL não invoca seu delegado se um token for encontrado no 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 declarações esperadas por Microsoft Entra ID na declaração assinada são:

Se você usar um certificado como um segredo do cliente, o certificado deverá ser implantado com segurança. Recomendamos que você armazene o certificado em um local seguro compatível com a plataforma, como no repositório de certificados no Windows ou usando Azure Key Vault.

Criando a asserção

Este é um exemplo usando Microsoft. IdentityModel.JsonWebTokens para criar a declaração para você.

        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);
        }

Como alternativa, se você não quiser usar 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 desenvolvedores querem injetar algumas declarações nas declarações, mas ainda gostariam que a MSAL lidasse com a criação da declaraçã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 outras declarações de cliente que você deseja 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 você passar for a mesma que uma das declarações obrigatórias, o valor da declaração adicional será levado em conta. Ele substitui as declarações computadas por MSAL.NET.

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