Compartilhar via


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

Importante

A partir de 1º de maio de 2025, o Azure AD B2C não estará mais disponível para compra para novos clientes. Saiba mais em nossas perguntas frequentes.

Antes de começar, use o seletor Escolha um tipo de política na parte superior dessa página 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 de usuários predefinidos ou por meio 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 do cliente OAuth 2.0 permite que um aplicativo (cliente confidencial) use suas próprias credenciais, em vez de representar um usuário, para autenticar ao chamar um recurso da Web, como 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 aplicativos geralmente 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 para um recurso, o recurso impõe que o próprio aplicativo tenha autorização para executar uma ação, pois 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.

Observação

Esse recurso se encontra em visualização pública.

Visão geral do registro do aplicativo

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

  • O registro do aplicativo permite que 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. Em seguida, você concede permissões de aplicativo aos 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:

Diagrama de um aplicativo web com registros de chamadas e tokens de Web API.

Etapa 1: Registrar o aplicativo de API Web

Nesta etapa, você registra a API Web (Aplicativo 2) com seus escopos. Posteriormente, você concede permissão ao aplicativo (Aplicativo 1) para esses escopos. Se você já tiver esse registro de aplicativo, ignore esta etapa e vá para a próxima, Etapa 1.1 Definir funções de API Web (escopos).

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

  1. Entre no portal do Azure.

  2. 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.

  3. 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 selecione Alternar.

  4. No portal do Azure, pesquise e selecione Azure AD B2C.

  5. Escolha Registros de aplicativo e Novo registro.

  6. 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.

  7. Selecione Registrar.

  8. Depois que o registro do aplicativo for concluído, selecione Visão Geral.

  9. Registre o valor da ID do aplicativo (cliente) para uso posterior, quando você configurar o aplicativo Web.

    A captura de tela demonstra como obter uma ID de aplicativo da API Web.

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

Nesta etapa, você configura o URI da ID do Aplicativo da API Web e define as funções do 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:

  1. Selecione a API Web que você criou, por exemplo, my-api1.

  2. Em Gerenciar, selecione Expor uma API.

  3. 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.

  4. Copie o URI da ID do aplicativo. A captura de tela a seguir mostra como copiar o URI da ID do aplicativo.

    Screenshot mostra como copiar o aplicativo I D.

  5. Em Gerenciar, selecione Manifesto para abrir o editor de manifesto do aplicativo. No editor, localize a configuração appRoles e defina funções de aplicativos que visam 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 new-guido comando no Microsoft PowerShell ou em 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 exemplo a seguir 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"
    }],
    
  6. 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 no 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:

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

Para criar um novo registro de aplicativo Web, siga estas etapas:

  1. No portal do Azure, pesquise pelo Azure AD B2C e selecione-o

  2. Escolha Registros de aplicativo e Novo registro.

  3. Insira um nome para o aplicativo. Por exemplo, ClientCredentials_app.

  4. Deixe os outros valores como estão e, então, selecione Registrar.

  5. Registre a ID do aplicativo (cliente) para uso em uma etapa posterior.

    Screenshot mostra como obter o aplicativo I D.

Etapa 2.1 Criar um segredo do cliente

Crie um segredo do cliente para o aplicativo registrado. Seu aplicativo usa o segredo do cliente para provar sua identidade quando solicita tokens.

  1. Em Gerenciar, selecione Certificados e segredos.

  2. Selecione Novo segredo do cliente.

  3. Na caixa Descrição , insira uma descrição para o segredo do cliente (por exemplo, clientsecret1).

  4. Em Expirar, selecione um período durante o qual o segredo será válido e clique em Adicionar.

  5. Registre o Valor do segredo. Use esse valor para configuração em uma etapa posterior.

    A captura de tela mostra como copiar o segredo do aplicativo.

Etapa 2.2 Conceder permissões ao aplicativo para a API Web

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

  1. Selecione Registros de aplicativo e, em seguida, selecione o aplicativo que você criou (Aplicativo 1).

  2. Em Gerenciar, selecione Permissões de API.

  3. Em Permissões Configuradas, selecione Adicionar uma permissão.

  4. Selecione a guia Minhas APIs.

  5. Selecione a API (App 2) à qual o aplicativo Web deve ter acesso. Por exemplo, insira my-api1.

  6. Selecione Permissão do aplicativo.

  7. Em Permissão, expanda app e selecione os escopos que você definiu anteriormente (por exemplo, app.read e app.write).

    A captura de tela mostra como conceder permissões ao aplicativo A P I.

  8. Selecione Adicionar Permissões.

  9. Selecione Fornecer consentimento do administrador para <nome do seu locatário>.

  10. Selecione Sim.

  11. 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. Os fluxos de usuário do Azure AD B2C e as políticas personalizadas dão suporte ao fluxo de credenciais do cliente. Se você ainda não tiver feito isso, 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 do seu locatário do Azure AD B2C. Por exemplo, contoso.b2clogin.com.
  • Substitua <policy> pelo nome completo do seu fluxo de usuário ou 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 você tenha ou criar uma nova, como inscrição ou entrada.
Chave Valor
tipo_de_concessão client_credentials
ID do cliente O ID do cliente da Etapa 2 Registrar um aplicativo.
segredo_do_cliente O valor do segredo do cliente da Etapa 2.1 Criar um segredo do cliente.
âmbito 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/00001111-aaaa-2222-bbbb-3333cccc4444/.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=11112222-bbbb-3333-cccc-4444dddd5555
&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": "11112222-bbbb-3333-cccc-4444dddd5555"
}

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 do cliente.

Reclamação Descrição Valor
aud Identifica o destinatário pretendido do token. A ID do 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 para a qual o token de acesso foi emitido. O ID do cliente do aplicativo que iniciou a solicitação. É o mesmo valor que você especificou no client_id da solicitação de autorização.
scp O conjunto de escopos expostos pela API do aplicativo (delimitador de espaço). No processo de credenciais do cliente, a solicitação de autorização requer o escopo .default, enquanto o token contém a lista de escopos expostos pela API e consentidos pelo administrador do aplicativo. 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 está disponível apenas para políticas personalizadas. Para as etapas de instalação, selecione Política personalizada no seletor anterior.

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

O exemplo a seguir mostra como adicionar o 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. A primeira e a última etapas de orquestração são necessá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>