Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
O código de autorização OAuth 2.0 concede entradas em um usuário e obtém tokens com permissões delegadas. O usuário entra por meio de um navegador, Microsoft Entra ID retorna um código de autorização de curta duração e o cliente resgata o código no ponto de extremidade do token.
Uma solução de ID do Agente pode usar a concessão de duas maneiras:
| Tipo de cliente | Papel típico | Credencial do cliente | PKCE |
|---|---|---|---|
| Cliente público | Um agente local entra diretamente no usuário. | No | Required |
| Cliente confidencial | Um cliente Web do lado do servidor entra no usuário antes de chamar um agente hospedado. | Yes | Recommended |
Use Biblioteca do Microsoft Authenticator (MSAL) ou Microsoft. Identity.Web em vez de criar essas solicitações diretamente. As solicitações neste artigo mostram os campos de protocolo para referência.
Warning
A Microsoft recomenda utilizar os SDKs aprovados, como as bibliotecas Microsoft.Identity.Web e Microsoft Entra ID Auth SDK (sidecar), para implementar esses protocolos. A implementação manual desses protocolos é complexa e propensa a erros e usar os SDKs ajuda a garantir a segurança e a conformidade com as práticas recomendadas.
Importante
O suporte à ID do agente do cliente público está em versão prévia. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou ter recursos restritos. Para obter mais informações, consulte Os Termos de Licença Universal para Serviços Online.
Solicitação de autorização
Ambos os tipos de cliente enviam o usuário para o ponto de extremidade de autorização do locatário:
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
client_id={client-id}
&response_type=code
&redirect_uri={encoded-redirect-uri}
&response_mode=query
&scope=openid%20profile%20offline_access%20api://{resource-client-id}/{scope}
&state={random-state}
&nonce={random-nonce}
&code_challenge={pkce-challenge}
&code_challenge_method=S256
-
client_ididentifica o cliente público ou confidencial. Um cliente público baseado em CIMD usa sua URL de documento de metadados HTTPS como a ID do cliente. -
redirect_urideve corresponder exatamente a um URI de redirecionamento configurado para o cliente. -
scopecontém as permissões delegadas que o cliente solicita. Omita o escopo do recurso quando o cliente só precisa entrar no usuário. -
stateassocia a resposta à sessão de início e ajuda a impedir a falsificação de solicitação entre sites. -
nonceassocia um token de ID do OpenID Connect à sessão de início. -
code_challengeé derivado de um verificador PKCE de alta entropia usando SHA-256.
Após a entrada e o consentimento, Microsoft Entra ID redireciona o navegador para o URI de redirecionamento registrado:
GET {redirect-uri}?code={authorization-code}&state={state}
Antes de resgatar o código, valide state e manipule qualquer erro OAuth retornado ao URI de redirecionamento.
Solicitação de token de cliente público
Um cliente público não pode proteger uma credencial de cliente. Ele resgata o código usando o verificador PKCE:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={agent-id-client-id-or-cimd-url}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{resource-client-id}/{scope}
&code_verifier={pkce-verifier}
Não envie um segredo do cliente, uma declaração de certificado ou uma credencial federada nesta solicitação.
Uma ID de agente do cliente público registrado deve usar o modo de instância única. Um cliente que usa um documento de metadados de ID do cliente pode usar a URL HTTPS do documento como sua ID do cliente. Para obter diretrizes de implementação, consulte Usuários de entrada de um agente local.
Solicitação de token de cliente confidencial
Um cliente confidencial é executado em um servidor que pode proteger credenciais. O servidor, não o código do navegador, resgata o código de autorização. A solicitação inclui uma credencial de cliente e o verificador PKCE quando a solicitação de autorização usou PKCE:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={confidential-client-id}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{agent-blueprint-client-id}/{scope}
&code_verifier={pkce-verifier}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed-client-assertion}
O exemplo usa uma declaração de cliente baseada em certificado. Também há suporte para um segredo do cliente, mas use uma federação de identidade de carga de trabalho ou certificado quando possível.
Em uma solução de ID do Agente hospedada, o cliente confidencial normalmente é o aplicativo Web upstream, não a ID do agente filho. Solicite um token de acesso cujo público-alvo é o blueprint do agente hospedado, envie esse token de acesso para a API do agente e use o fluxo on-Behalf-Of para chamar APIs downstream.
Para uma identidade de agente de instância única (versão prévia), <agent-blueprint-client-id> denota a ID do cliente compartilhada pelo blueprint e pela identidade do agente. Para uma frota, ela indica a ID do cliente do blueprint, não a ID de um agente filho individual. Para o modo de instância única, configure a concessão do cliente upstream por meio da concessão do acesso do cliente upstream antes da entrada; O consentimento do navegador não dá suporte à identidade do agente como um recurso.
Não envie um código de autorização ou token de ID para a API do agente hospedado. As IDs do Agente Filho no padrão de cliente confidencial não iniciam uma solicitação interativa /authorize .
Resposta do token
Se a solicitação for bem-sucedida, Microsoft Entra ID retornará tokens como:
{
"token_type": "Bearer",
"scope": "api://<resource-client-id>/<scope>",
"expires_in": 3599,
"access_token": "<access-token>",
"refresh_token": "<refresh-token>",
"id_token": "<id-token>"
}
A resposta exata depende dos escopos solicitados:
- Use o token de acesso somente com o recurso identificado por sua
auddeclaração. - Use o token de ID para estabelecer a sessão de entrada do usuário, não para chamar uma API.
- Um token de atualização é retornado quando a solicitação e a política permitem o acesso offline.
Requisitos de segurança
- Use o PKCE com o
S256método de desafio para clientes públicos. Use também o PKCE para clientes confidenciais quando a biblioteca der suporte a ele. - Corresponda ao URI de redirecionamento exatamente nas solicitações de autorização e token.
- Gere um novo verificador
noncePKCE e um novostateverificador PKCE para cada solicitação de autorização. - Resgatar um código de autorização apenas uma vez e somente do cliente que iniciou a solicitação.
- Não registre códigos de autorização, credenciais do cliente, tokens de acesso, tokens de atualização ou tokens de ID.
- Validar tokens de acesso na API. Não trate a posse de um código de autorização ou token de ID como autorização de API.
Conteúdo relacionado
- plataforma de identidade da Microsoft e fluxo de código de autorização do OAuth 2.0
- Clientes públicos e aplicativos cliente confidenciais
- Restrições e limitações de URI de redirecionamento
- Credenciais de certificado para autenticação de aplicativo
- Escolher um protocolo de autenticação para um agente