Definir um perfil técnico de dica de token de ID em uma política personalizada B2C do Azure Ative Directory

Artigo
01/11/2024

O Azure AD B2C permite que aplicativos de terceira parte confiável enviem um JWT de entrada como parte da solicitação de autorização OAuth2. O token JWT pode ser emitido por um aplicativo de terceira parte confiável ou um provedor de identidade, e pode passar uma dica sobre o usuário ou a solicitação de autorização. O Azure AD B2C valida a assinatura, o nome do emissor e o público do token e extrai a declaração do token de entrada.

Casos de utilização

Você pode usar essa solução para enviar dados para o Azure AD B2C encapsulados em um único token JWT. A Signup with email invitation solução, em que o administrador do sistema pode enviar um convite assinado aos usuários, é baseada em id_token_hint. Somente os usuários com acesso ao e-mail de convite podem criar a conta no diretório.

Abordagem de assinatura de token

Com id_token_hint, o emissor do token (um aplicativo de terceira parte confiável ou um provedor de identidade) compõe o token e, em seguida, assina-o usando uma chave de assinatura para provar que o token vem de uma fonte confiável. A chave de assinatura pode ser simétrica ou assimétrica. A criptografia simétrica, ou criptografia de chave privada, usa um segredo compartilhado para assinar e validar a assinatura. A criptografia assimétrica, ou criptografia de chave pública, é um sistema criptográfico que usa uma chave privada e uma chave pública. A chave privada é conhecida apenas pelo emissor do token e é usada para assinar o token. A chave pública é compartilhada com a política B2C do Azure AD para validar a assinatura do token.

Formato do token

O id_token_hint deve ser um token JWT válido. A tabela a seguir lista as declarações que são obrigatórias. Reclamações adicionais são opcionais.

Nome	Afirmação	Valor de exemplo	Description
Audiência	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Identifica o destinatário pretendido do token. A audiência é uma cadeia de caracteres arbitrária definida pelo emissor do token. O Azure AD B2C valida esse valor e rejeita o token se ele não corresponder.
Emissor	`iss`	`https://localhost`	Identifica o serviço de token de segurança (emissor de token). O emissor é um URI arbitrário definido pelo emissor do token. O Azure AD B2C valida esse valor e rejeita o token se ele não corresponder.
Expiration time	`exp`	`1600087315`	O momento em que o token se torna inválido, representado no tempo de época. O Azure AD B2C valida esse valor e rejeita o token se ele tiver expirado.
Não antes	`nbf`	`1599482515`	O momento em que o token se torna válido, representado em tempo de época. Este tempo é geralmente o mesmo que o tempo em que o token foi emitido. O Azure AD B2C valida esse valor e rejeita o token se o tempo de vida do token não for válido.

O token a seguir é um exemplo de um token de ID válido:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}

Protocolo

O atributo Name do elemento Protocol precisa ser definido como None. Por exemplo, o protocolo para o perfil técnico IdTokenHint_ExtractClaims é None:

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

O perfil técnico é chamado a partir de uma etapa de orquestração com o tipo de GetClaims.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Declarações de saída

O elemento OutputClaims contém uma lista de declarações a serem extraídas do token JWT. Talvez seja necessário mapear o nome da declaração definida em sua política para o nome definido no token JWT. Você também pode incluir declarações que não são retornadas pelo token JWT, desde que você defina o DefaultValue atributo.

Metadados

Os metadados a seguir são relevantes ao usar a chave simétrica.

Atributo	Obrigatório	Description
emitente	Sim	Identifica o serviço de token de segurança (emissor de token). Esse valor deve ser idêntico à `iss` declaração dentro da declaração de token JWT.
IdTokenAudience	Sim	Identifica o destinatário pretendido do token. Deve ser idêntico à `aud` declaração dentro da declaração de token JWT.

Os metadados a seguir são relevantes ao usar uma chave assimétrica.

Atributo	Obrigatório	Description
METADADOS	Sim	Uma URL que aponta para um documento de configuração do emissor de token, que também é conhecido como um ponto de extremidade de configuração conhecido do OpenID.
emitente	Não	Identifica o serviço de token de segurança (emissor de token). Esse valor pode ser usado para substituir o valor configurado nos metadados e deve ser idêntico à `iss` declaração dentro da declaração de token JWT.
IdTokenAudience	Não	Identifica o destinatário pretendido do token. Deve ser idêntico à `aud` declaração dentro da declaração de token JWT.

Importante

Seus pontos de extremidade devem estar em conformidade com os requisitos de segurança do Azure AD B2C. Versões e cifras TLS mais antigas foram preteridas. Para obter mais informações, consulte Azure AD B2C TLS e requisitos do pacote de codificação.

Chaves criptográficas

Ao usar uma chave simétrica, o elemento CryptographicKeys contém o seguinte atributo:

Atributo	Obrigatório	Description
client_secret	Sim	A chave criptográfica usada para validar a assinatura do token JWT.

Manual de instruções

Emitir um token com chaves simétricas

Etapa 1: Criar uma chave compartilhada

Crie uma chave que possa ser usada para assinar o token. Por exemplo, use o seguinte código do PowerShell para gerar uma chave.

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

Esse código cria uma cadeia de caracteres secreta como VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Etapa 2: Adicionar a chave de assinatura ao Azure AD B2C

A mesma chave usada pelo emissor do token precisa ser criada em suas chaves de política do Azure AD B2C.

Inicie sessão no portal do Azure.
Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para seu locatário do Azure AD B2C no menu Diretórios + assinaturas .
No portal do Azure, procure e selecione Azure AD B2C.
Na página de visão geral, em Políticas, selecione Identity Experience Framework.
Selecionar chaves de política
Selecione Manual.
Para Nome, use IdTokenHintKey.
O prefixo B2C_1A_ pode ser adicionado automaticamente.
Na caixa Segredo, introduza a chave de início de sessão que gerou anteriormente.
Para o uso da chave, use a criptografia.
Selecione Criar.
Confirme que criou a chave B2C_1A_IdTokenHintKey.

Etapa 3: Adicionar o perfil técnico de dica de token de ID

O perfil técnico a seguir valida o token e extrai as declarações.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">a489fc44-3cc0-4a78-92f6-e413cd853eae</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Passo 4: Preparar a sua política

Conclua a etapa Configurar sua política .

Etapa 5: Preparar o código

O exemplo GitHub é um aplicativo Web ASP.NET e aplicativo de console que gera um token de ID que é assinado usando uma chave simétrica.

Emitir um token com chaves assimétricas

Com uma chave assimétrica, o token é assinado usando certificados RSA. Este aplicativo hospeda um ponto de extremidade de metadados OpenID Connect e um ponto de extremidade JSON Web Keys (JWKs) que é usado pelo Azure AD B2C para validar a assinatura do token de ID.

O emissor do token deve fornecer os seguintes pontos de extremidade:

/.well-known/openid-configuration - Um ponto de extremidade de configuração bem conhecido com informações relevantes sobre o token, como o nome do emissor do token e o link para o ponto de extremidade JWK.
/.well-known/keys - o ponto final JSON Web Key (JWK) com a chave pública que é usada para assinar a chave (com a parte de chave privada do certificado).

Consulte o exemplo de TokenMetadataController.cs controlador .NET MVC.

Etapa 1: Preparar um certificado autoassinado

Se você ainda não tiver um certificado, poderá usar um certificado autoassinado para este guia de instruções. No Windows, você pode usar o cmdlet New-SelfSignedCertificate do PowerShell para gerar um certificado.

Execute este comando do PowerShell para gerar um certificado autoassinado. Modifique o -Subject argumento conforme apropriado para seu aplicativo e nome de locatário do Azure AD B2C. Você também pode ajustar a -NotAfter data para especificar uma expiração diferente para o certificado.

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

Etapa 2: Adicionar o perfil técnico de dica de token de ID

O perfil técnico a seguir valida o token e extrai as declarações. Altere o URI de metadados para o ponto de extremidade de configuração conhecido do emissor do token.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.azurewebsites.net/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Passo 3: Preparar a sua política

Conclua a etapa Configurar sua política .

Etapa 4: Preparar o código

Este exemplo do GitHub ASP.NET aplicativo Web gera tokens de ID e hospeda os pontos de extremidade de metadados necessários para usar o parâmetro "id_token_hint" no Azure AD B2C.

Configurar a sua política

Para abordagens simétricas e assimétricas, o perfil técnico é chamado a partir de uma etapa de orquestração com o id_token_hint tipo de e precisa especificar as declarações de entrada da política de GetClaims terceira parte confiável.

Adicione o perfil técnico IdTokenHint_ExtractClaims à sua política de extensão.

Adicione a seguinte etapa de orquestração à sua jornada do usuário como o primeiro item.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Em sua política de terceira parte confiável, repita as mesmas declarações de entrada que você configurou no perfil técnico IdTokenHint_ExtractClaims. Por exemplo:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Dependendo dos requisitos da sua empresa, talvez seja necessário adicionar validações de token, por exemplo, verifique o formato do endereço de e-mail. Para fazer isso, adicione etapas de orquestração que invoquem um perfil técnico de transformação de declarações. Adicione também um perfil técnico autodeclarado para apresentar uma mensagem de erro.

Criar e assinar um token

Os exemplos do GitHub ilustram como criar um problema de token como um JWT que mais tarde foi enviado como um id_token_hint parâmetro de cadeia de caracteres de consulta. Segue-se um exemplo de um pedido de autorização com id_token_hint parâmetro

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

Próximos passos

Verifique a inscrição com a solução de email de convite no repositório GitHub da comunidade do Azure AD B2C.

Partilhar via