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

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 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 uso

Você pode usar essa solução para enviar dados para o Azure AD B2C encapsulados em um único 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 JWT válido. A tabela a seguir lista as declarações que são obrigatórias. Reclamações adicionais são opcionais.

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": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

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 JWT. Talvez seja necessário mapear o nome da declaração definida em sua política para o nome definido no JWT. Você também pode incluir declarações que não são retornadas pelo JWT, desde que você defina o DefaultValue atributo.

Metadados

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

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

Chaves criptográficas

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

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.

1. Inicie sessão no portal Azure.
2. Se tiver acesso a vários inquilinos, selecione o ícone Definições no menu superior para mudar para o inquilino do Azure AD B2C no menu Diretórios + subscrições.
3. No portal do Azure, procure e selecione Azure AD B2C.
4. Na página de visão geral, em Políticas, selecione Identity Experience Framework.
5. Selecione Chaves de Política
6. Selecione Manual.
7. Para Nome, use IdTokenHintKey.
   O prefixo B2C_1A_ pode ser adicionado automaticamente.
8. Na caixa Segredo , introduza a chave de início de sessão que gerou anteriormente.
9. Para o uso da chave, use a criptografia.
10. Selecione Criar.
11. 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">00001111-aaaa-2222-bbbb-3333cccc4444</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 do GitHub é um aplicativo Web ASP.NET e um aplicativo de console que gera um token de ID 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 aplicativo Web de exemplo ASP.NET GitHub 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 id_token_hint perfil técnico é chamado a partir de uma etapa de orquestração com o tipo de e precisa especificar as declarações de entrada da política de GetClaims terceira parte confiável.

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

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

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

3. 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=11112222-bbbb-3333-cccc-4444dddd5555&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.