Configurar o fluxo de credenciais de cliente do OAuth 2.0 no Azure Active Directory B2C

Artigo
11/21/2023

Antes de começar, use o seletor Escolher um tipo de política para escolher o tipo de política que você está configurando. O Azure Active Directory B2C oferece dois métodos para definir como os usuários interagem com seus aplicativos: por meio de fluxos dos usuários predefinidos ou de políticas personalizadas totalmente configuráveis. As etapas necessárias neste artigo são diferentes para cada método.

O fluxo de concessão de credenciais de cliente do OAuth 2.0 permite que um aplicativo (cliente confidencial) use credenciais próprias, em vez de representar um usuário, para autenticar ao chamar outro serviço Web, com a API REST. Esse tipo de concessão normalmente é usado para interações de servidor para servidor que devem ser executadas em segundo plano, sem interação imediata com um usuário. Esses tipos de aplicativo normalmente são chamados de daemons ou contas de serviço.

No fluxo de credenciais do cliente, as permissões são concedidas diretamente ao próprio aplicativo por um administrador. Quando o aplicativo apresenta um token a um recurso, o recurso impõe que o próprio aplicativo tenha autorização para executar uma ação, já que não há nenhum usuário envolvido na autenticação. Este artigo aborda as etapas necessárias para autorizar um aplicativo a chamar uma API e como obter os tokens necessários para chamar essa API.

Este recurso está em visualização pública.

Visão geral do registro do aplicativo

Para permitir que o aplicativo entre com credenciais de cliente, chame uma API Web, registre dois aplicativos no diretório do Azure AD B2C.

O registro de aplicativo permite que o seu aplicativo entre com o Azure AD B2C. O processo de registro de aplicativo gera uma ID de aplicativo, também conhecida como ID do cliente, que identifica o aplicativo de modo exclusivo. Você também cria um segredo do cliente, que o aplicativo usa para adquirir os tokens com segurança.
O registro da API Web permite que o aplicativo chame uma API Web segura. O registro inclui os escopos da API Web. Os escopos fornecem uma forma de gerenciar as permissões em recursos protegidos, como a API Web. Assim, você concede ao seu aplicativo permissões para acessar os escopos da API Web. Ao solicitar um token de acesso, o aplicativo especifica o parâmetro de escopo .default da solicitação. O Azure AD B2C retorna os escopos da API Web concedidos ao seu aplicativo.

A arquitetura e os registros do aplicativo são ilustrados no diagrama a seguir:

Diagram of a web app with web A P I call registrations and tokens.

Etapa 1: Registrar o aplicativo de API Web

Nesta etapa, você registra a API Web (aplicativo 2) com os respectivos escopos. Posteriormente, você concede ao seu aplicativo (aplicativo 1) permissões para acessar esses escopos. Se você já possui esse registro de aplicativo, pule esta etapa e vá para a próxima, Etapa 1.1 Definir funções (escopos) da API Web.

Para criar o registro do aplicativo da API Web (ID do Aplicativo: 2), siga estas etapas:

Entre no portal do Azure.
Verifique se você está usando o diretório que contenha seu locatário do Azure AD B2C. Selecione o ícone Diretórios + assinaturas na barra de ferramentas do portal.
Na página Configurações do portal | Diretórios + assinaturas, encontre o diretório Azure Active Directory B2C na lista Nome do diretório e, em seguida, selecione Alternar.
No portal do Azure, pesquise e selecione Azure AD B2C.
Escolha Registros de aplicativo e Novo registro.
Insira um Nome para o aplicativo, (por exemplo, my-api1). Deixe os valores padrão para URI de redirecionamento e tipos de conta com suporte.
Selecione Registrar.
Depois que o registro do aplicativo for concluído, selecione Visão Geral.
Registre o valor da ID do aplicativo (cliente) para uso posterior, quando você configurar o aplicativo Web.

Etapa 1.1 – Definir funções da API Web (escopos)

Nesta etapa, você configura o URI da ID do Aplicativo da API Web e define Funções de aplicativo. As funções de aplicativo, usadas pelos escopos do OAuth 2.0 e definidas em um registro de aplicativo que representa sua API. Seu aplicativo usa o URI da ID do Aplicativo com o escopo .default. Para definir funções de aplicativo, siga estas etapas:

Selecione a API Web que você criou, por exemplo, my-api1.
Em Gerenciar, selecione Expor uma API.
Ao lado de URI do ID do Aplicativo, selecione o link Definir. Substitua o valor padrão (GUID) por um nome exclusivo (por exemplo, api) e selecione Salvar.
Copie o URI da ID do aplicativo. A captura de tela a seguir mostra como copiar o URI da ID do Aplicativo.
Em Gerenciar, selecione Manifesto para abrir o editor de manifesto do aplicativo. No editor, localize a configuração appRoles e defina as funções de aplicativo direcionadas a applications. Cada definição de função de aplicativo deve ter um GUID (identificador exclusivo) global para seu valor de id. Gere um novo GUID executando o comando new-guid no Microsoft PowerShell ou um gerador de GUID online. A propriedade value de cada definição de função de aplicativo aparece no escopo, na declaração scp. A propriedade value não pode conter espaços. O seguinte exemplo demonstra duas funções de aplicativo, leitura e gravação:
```
"appRoles": [
{
  "allowedMemberTypes": ["Application"],
  "displayName": "Read",
  "id": "d6a15e20-f83c-4264-8e61-5082688e14c8",
  "isEnabled": true,
  "description": "Readers have the ability to read tasks.",
  "value": "app.read"
},
{
  "allowedMemberTypes": ["Application"],
  "displayName": "Write",
  "id": "204dc4ab-51e1-439f-8c7f-31a1ebf3c7b9",
  "isEnabled": true,
  "description": "Writers have the ability to create tasks.",
  "value": "app.write"
}],
```
Na parte superior da página, selecione Salvar para salvar as alterações do manifesto.

Etapa 2: Registrar um aplicativo

Para permitir que seu aplicativo entre com Azure AD B2C usando o fluxo de credenciais do cliente, você pode usar um aplicativo existente ou registrar um novo (Aplicativo 1).

Se você estiver usando um aplicativo existente, verifique se o aplicativo accessTokenAcceptedVersion está definido como 2:

No portal do Azure, pesquise e selecione Azure AD B2C.
Selecione Registros de aplicativo e selecione o aplicativo existente na lista.
No menu à esquerda, em Gerenciar, selecione Manifesto para abrir o editor de manifesto.
Localize o elemento accessTokenAcceptedVersion e defina seu valor como 2.
Na parte superior da página, selecione Salvar para salvar as alterações.

Siga estas etapas para criar um novo registro de aplicativo Web:

No portal do Azure, pesquise pelo Azure AD B2C e selecione-o
Escolha Registros de aplicativo e Novo registro.
Insira um Nome para o aplicativo. Por exemplo, ClientCredentials_app.
Deixe os outros valores como estão e, então, selecione Registrar.
Registre a ID do aplicativo (cliente) para uso em uma etapa posterior.

Etapa 2.1 – Criar um segredo do cliente

Crie um segredo do cliente para o aplicativo registrado. O aplicativo usa o segredo do cliente para confirmar a identidade ao solicitar tokens.

Em Gerenciar, selecione Certificados & Segredos.
Selecione Novo segredo do cliente.
Na caixa Descrição, insira uma descrição para o segredo do cliente (por exemplo, clientsecret1).
Em Expirar, selecione um período durante o qual o segredo será válido e clique em Adicionar.
Registre o Valor do segredo. Você usará esse valor para uma configuração em uma etapa posterior.

Etapa 2.2 – Conceder permissões de aplicativo para a API Web

Para conceder permissões ao seu aplicativo (aplicativo 1), siga estas etapas:

Selecione Registros de aplicativo, depois escolha o aplicativo que você criou (aplicativo 1).
Em Gerenciar, selecione Permissões de API.
Em Permissões Configuradas, selecione Adicionar uma permissão.
Selecione a guia Minhas APIs.
Selecione a API (aplicativo 2) a que o aplicativo Web deve receber acesso. Por exemplo, insira my-api1.
Selecione permissão de aplicativo.
Em Permissão, expanda aplicativo e selecione os escopos definidos anteriormente (por exemplo, app.read e app.write).
Selecione Adicionar Permissões.
Selecione Fornecer consentimento do administrador para <nome do seu locatário>.
Selecione Sim.
Selecione Atualizar e, em seguida, verifique se Concedido para... aparece em Status para ambos os escopos.

Etapa 3: Obter um token de acesso

Não há ações específicas para habilitar as credenciais do cliente para fluxos de usuário ou políticas personalizadas. Tanto os fluxos de usuário do Azure AD B2C quanto as políticas personalizadas dão suporte ao fluxo de credenciais de cliente. Caso ainda não tenha feito, crie um fluxo de usuário ou uma política personalizada. Em seguida, use seu aplicativo de desenvolvimento de API favorito para gerar uma solicitação de autorização. Construa uma chamada de exemplo com as seguintes informações no corpo da solicitação POST:

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy>/oauth2/v2.0/token

Substitua <tenant-name> pelo nome de seu locatário do Azure AD B2C. Por exemplo, contoso.b2clogin.com.
Substitua <policy> pelo nome completo do fluxo de usuário ou pela política personalizada. Observe que todos os tipos de fluxos de usuário e políticas personalizadas dão suporte ao fluxo de credenciais do cliente. Você pode usar qualquer fluxo de usuário ou política personalizada que tiver – ou criar do zero – como inscrição ou entrada.

Chave	Valor
grant_type	`client_credentials`
client_id	A ID do cliente da Etapa 2 – Registrar um aplicativo.
client_secret	O valor do Segredo do cliente da Etapa 2.1 – Criar um segredo do cliente.
scope	O URI da ID do Aplicativo da Etapa 1.1 – Definir funções da API Web (escopos) e `.default`. Por exemplo, `https://contoso.onmicrosoft.com/api/.default` ou `https://contoso.onmicrosoft.com/12345678-0000-0000-0000-000000000000/.default`.

A solicitação POST real tem a aparência do exemplo a seguir:

Solicitação:

POST /<tenant-name>.onmicrosoft.com/B2C_1A_SUSI/oauth2/v2.0/token HTTP/1.1
Host: <tenant-name>.b2clogin.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=33333333-0000-0000-0000-000000000000
&client_secret=FyX7Q~DuPJ...
&scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fapi%2F.default

Resposta:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5OZDlnUkNWWUc2dUs...",
    "token_type": "Bearer",
    "not_before": 1645172292,
    "expires_in": 3600,
    "expires_on": 1645175892,
    "resource": "33333333-0000-0000-0000-000000000000"
}

Saiba mais sobre as declarações de token de acesso de retorno. A tabela a seguir lista as declarações relacionadas ao fluxo de credenciais de cliente.

Declaração	Descrição	Valor
`aud`	Identifica o destinatário pretendido do token.	A ID de cliente da API.
`sub`	A entidade de serviço associa ao aplicativo que iniciou a solicitação.	É a entidade de serviço de `client_id` da solicitação de autorização.
`azp`	Parte autorizada – a parte à qual o token de acesso foi emitido.	A ID do cliente do aplicativo que iniciou a solicitação. É o mesmo valor especificado em `client_id` da solicitação de autorização.
`scp`	O conjunto de escopos expostos pela API do aplicativo (delimitador de espaço).	No fluxo de credenciais de cliente, a solicitação de autorização requisita o escopo `.default`, enquanto o token contém a lista de escopos expostos (e consentidos pelo administrador do aplicativo) pela API. Por exemplo, `app.read app.write`.

Etapa 3.1 – Obter um token de acesso com script

Use o seguinte script do PowerShell para testar sua configuração:

$appId = "<client ID>"
$secret = "<client secret>"
$endpoint = "https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy>/oauth2/v2.0/token"
$scope = "<Your API id uri>/.default"
$body = "grant_type=client_credentials&scope=" + $scope + "&client_id=" + $appId + "&client_secret=" + $secret

$token = Invoke-RestMethod -Method Post -Uri $endpoint -Body $body

Use o seguinte script cURL para testar sua configuração:

curl --location --request POST 'https://<your-tenant>.b2clogin.com/<your-tenant>.onmicrosoft.com/<policy>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'grant_type="client_credentials"' \
--form 'client_id="<client ID>"' \
--form 'client_secret="<client secret>"' \
--form 'scope="<Your API id uri>/.default"'

Etapa 4: Personalizar o token

Esse recurso só está disponível para políticas personalizadas. Para obter as etapas de instalação, escolha Política personalizada no seletor anterior.

As políticas personalizadas fornecem uma forma de estender o processo de emissão de token. Para personalizar o percurso do usuário com as credenciais de cliente do OAuth 2.0, siga as Diretrizes sobre como configurar um percurso de usuário com as credenciais de cliente. Em seguida, no perfil técnico JwtIssuer, adicione os metadados ClientCredentialsUserJourneyId com uma referência ao percurso do usuário criado.

O exemplo a seguir mostra como adicionar ClientCredentialsUserJourneyId ao perfil técnico do emissor do token.

<TechnicalProfile Id="JwtIssuer">
  <Metadata>
    <Item Key="ClientCredentialsUserJourneyId">ClientCredentialsJourney</Item>
  </Metadata>
</TechnicalProfile>

O exemplo a seguir mostra um percurso de usuário com as credenciais de cliente. As primeiras e as últimas etapas da orquestração são obrigatórias.

<UserJourneys>
  <UserJourney Id="ClientCredentialsJourney">
    <OrchestrationSteps>
      <!-- [Required] Do the client credentials -->
      <OrchestrationStep Order="1" Type="ClaimsExchange">
        <ClaimsExchanges>
          <ClaimsExchange Id="ClientCredSetupExchange" TechnicalProfileReferenceId="ClientCredentials_Setup" />
        </ClaimsExchanges>
      </OrchestrationStep>

      <!-- [Optional] Call a REST API or claims transformation -->
      <OrchestrationStep Order="2" Type="ClaimsExchange">
        <ClaimsExchanges>
          <ClaimsExchange Id="TokenAugmentation" TechnicalProfileReferenceId="TokenAugmentation" />
        </ClaimsExchanges>
      </OrchestrationStep>

      <!-- [Required] Issue the access token -->
      <OrchestrationStep Order="3" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
    </OrchestrationSteps>
  </UserJourney>
</UserJourneys>

Próximas etapas

Saiba como configurar o fluxo de credenciais de senha do proprietário do recurso no Azure AD B2C

Compartilhar via