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.
Usando um CIMD (Documento de Metadados de ID do Cliente), seu cliente OAuth pode usar uma URL HTTPS pública como sua client_id. Este artigo explica como publicar um documento CIMD e usá-lo para solicitar um token de acesso delegado de Microsoft Entra ID.
Importante
O suporte ao Documento de Metadados de ID do Cliente no Microsoft Entra ID está em versão prévia pública. 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.
Antes de implementar o CIMD, examine os documentos de metadados da ID do cliente no Microsoft Entra ID para entender os cenários com suporte, o modelo de segurança e as limitações.
Prerequisites
Para concluir esse procedimento, é necessário:
- Um cliente OAuth que dá suporte ao fluxo de código de autorização e ao PKCE.
- Um ponto de extremidade HTTPS público estável em que você pode publicar um documento JSON.
- Um servidor MCP protegido com Microsoft Entra ID. Consulte Preparar o servidor MCP.
- Um locatário do Microsoft Entra no qual o suporte ao CIMD está disponível.
- Um administrador do locatário que pode adicionar o cliente CIMD e conceder permissões delegadas quando o consentimento do usuário não estiver disponível. Forneça ao administrador a URL do documento, o recurso de destino e os escopos solicitados antes de testar o login.
O cliente deve ser capaz de abrir um navegador para login do usuário. Os clientes CIMD não podem usar a concessão de credenciais do cliente.
Preparar o servidor MCP
Um cliente CIMD não tem registro de aplicativo, portanto, ele aprende tudo sobre o servidor MCP a partir dos metadados de recursos protegidos do servidor e de Microsoft Entra ID. Configure o servidor seguindo Proteger um servidor MCP com Microsoft Entra ID. Esse artigo aborda o registro do servidor, a exposição de um escopo delegado, a publicação de metadados de recursos protegidos e a validação de tokens de acesso.
Em seguida, confirme as configurações a seguir. Os exemplos neste artigo usam um servidor MCP em https://mcp.contoso.com que expõe o escopo mcp.access.
| Configuração | Valor obrigatório | Example |
|---|---|---|
| URI da ID do aplicativo do registro de aplicativo do servidor | A URL canônica do servidor. | https://mcp.contoso.com |
resource nos metadados do recurso protegido |
O mesmo valor que o URI da ID do aplicativo. O cliente envia esse valor em seu parâmetro resource, e o Microsoft Entra ID emite o token com esse audience. |
https://mcp.contoso.com |
authorization_servers nos metadados de recursos protegidos |
O Microsoft Entra URL do servidor de autorização para o locatário ou common para um servidor multilocatário. |
https://login.microsoftonline.com/{tenant}/oauth21/2026-08 |
scopes_supported nos metadados do recurso protegido |
O escopo delegado que o cliente solicita. | mcp.access |
| Quem pode consentir com o escopo delegado | Administradores e usuários permite que os usuários consintam com o aplicativo cliente, se a política de consentimento do locatário permitir. Somente administradores exige que um administrador aprove o cliente. | Administradores e usuários |
| Tipos de conta com suporte |
Vários locatários Entra ID quando authorization_servers usa common. |
Inquilino único |
Verifique se o servidor publica seus metadados:
GET https://mcp.contoso.com/.well-known/oauth-protected-resource
A resposta deve conter os valores resource, scopes_supported e authorization_servers da tabela anterior. O servidor MCP não precisa de lógica de validação de token específica do CIMD. Microsoft Entra ID emite o token de acesso e o servidor o valida como qualquer outro token de acesso.
Publicar o documento de metadados
Publique um documento JSON na URL que você pretende usar como a ID do cliente. Por exemplo:
GET https://client.contoso.com/oauth/client-metadata.json
Content-Type: application/json
{
"client_id": "https://client.contoso.com/oauth/client-metadata.json",
"client_name": "Contoso Agent",
"client_uri": "https://client.contoso.com",
"logo_uri": "https://client.contoso.com/logo.png",
"redirect_uris": [
"https://client.contoso.com/oauth/callback"
],
"grant_types": [
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"token_endpoint_auth_method": "none",
"scope": "offline_access https://mcp.contoso.com/mcp.access"
}
Siga estes requisitos:
- Use uma URL HTTPS com um caminho não vazio.
- Não inclua informações do usuário ou um fragmento na URL.
- Defina
client_idcomo a URL exata que fornece o documento. - Mantenha a URL curta e estável. Ele pode aparecer em experiências de consentimento e administração.
- Liste cada URI de redirecionamento que o cliente pode usar. Microsoft Entra ID usa a correspondência exata da cadeia de caracteres.
- Use URIs de redirecionamento HTTPS. Os URIs de redirecionamento de loopback podem ser usados para cenários locais de cliente nativo em que a especificação OAuth aplicável permite.
- Não confie em redirecionamentos HTTP quando o Microsoft Entra ID recupera o documento.
- Retornar um status HTTP bem-sucedido e uma resposta JSON válida.
- Não use um segredo do cliente compartilhado. Defina
token_endpoint_auth_methodcomononepara um cliente público.
O formato do documento é definido pela especificação do Documento de Metadados da ID do Cliente OAuth.
Caution
Trate a URL do documento e seu domínio como ativos de segurança de longa duração. Se você mover o documento para outra URL, Microsoft Entra ID o tratará como um cliente diferente. As concessões de consentimento existentes não são transferidas.
Verificar o suporte ao servidor de autorização
Antes de enviar uma URL como uma ID do cliente, confirme se o servidor de autorização para o locatário de destino dá suporte ao CIMD.
Identifique o servidor de autorização. Para um servidor MCP, busque os metadados do recurso protegido em
<server-url>/.well-known/oauth-protected-resourcee leia o valor deauthorization_servers:GET https://mcp.contoso.com/.well-known/oauth-protected-resource{ "resource": "https://mcp.contoso.com", "authorization_servers": ["https://login.microsoftonline.com/{tenant}/oauth21/2026-08"] }Para outros recursos protegidos, use
https://login.microsoftonline.com/{tenant}/oauth21/2026-08, onde{tenant}estivercommon, a ID do locatário ou um domínio verificado da organização.Busque os metadados do servidor de autorização acrescentando
/.well-known/openid-configurationà URL do servidor de autorização:GET https://login.microsoftonline.com/{tenant}/oauth21/2026-08/.well-known/openid-configurationVerifique se a resposta contém a propriedade
client_id_metadata_document_supported. Um servidor de autorização compatível com CIMD retornatrue:{ "client_id_metadata_document_supported": true }A resposta contém outras propriedades que não são mostradas aqui, incluindo
authorization_endpointetoken_endpoint. Um cliente que usa a descoberta de metadados, como um cliente MCP, envia suas solicitações para esses pontos de extremidade. Os exemplos a seguir usam os pontos de extremidade Microsoft Entra v2.0, que também dão suporte a IDs de cliente CIMD.
Não envie uma ID do cliente CIMD quando a propriedade não estiver definida ou false. Recorra a uma ID de cliente registrada ou outro método de registro compatível com o servidor de autorização.
Enviar a solicitação de autorização
Defina client_id como a URL do documento de metadados. Para um servidor MCP, inclua também a URL de recurso protegida no resource parâmetro.
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
?client_id=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fclient-metadata.json
&response_type=code
&redirect_uri=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fcallback
&scope=offline_access%20https%3A%2F%2Fmcp.contoso.com%2Fmcp.access
&resource=https%3A%2F%2Fmcp.contoso.com
&code_challenge={PKCE_challenge}
&code_challenge_method=S256
&state={opaque_value}
Substituir:
-
{tenant}com o identificador de locatário ou domínio verificado para a organização. -
{PKCE_challenge}com o desafio S256 gerado a partir do seu verificador de código. -
{opaque_value}com um valor que seu cliente valida quando a resposta de autorização é retornada. - Os valores de recurso e escopo devem corresponder aos publicados pelo servidor MCP.
Microsoft Entra ID recupera e valida o documento de metadados. O redirect_uri solicitado deve corresponder exatamente a um dos valores em redirect_uris.
Dependendo da política de locatário e se um administrador adicionou o cliente com antecedência, o usuário pode:
- Continue sem um novo prompt porque um administrador já concedeu consentimento.
- Consentimento para permissões delegadas de baixo risco.
- Seja informado de que a aprovação do administrador é necessária.
- Ser impedido de adicionar o cliente.
A solicitação de autorização é uma maneira de conceder permissões delegadas à identidade do agente do cliente. Para os outros métodos, incluindo o consentimento do administrador, consulte Conceder permissões delegadas a uma identidade de agente.
Durante a visualização, conceda permissões por meio dos pontos de extremidade de entrada e consentimento ou Microsoft Graph, e não pela experiência de permissões no portal. O fluxo de trabalho de solicitação de consentimento do administrador está desativado para o Agent ID, incluindo clientes CIMD. Em um locatário padrão, planeje que um administrador adicione o cliente e conceda consentimento antes que os usuários entrem; não confie no consentimento do usuário disponível.
Resgatar o código de autorização
Depois que Microsoft Entra ID retornar um código de autorização, resgate-o no ponto de extremidade do token v2 do locatário:
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fclient-metadata.json&
grant_type=authorization_code&
code={authorization_code}&
redirect_uri=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fcallback&
code_verifier={PKCE_code_verifier}&
scope=https%3A%2F%2Fmcp.contoso.com%2Fmcp.access&
resource=https%3A%2F%2Fmcp.contoso.com
Valide o state valor antes de resgatar o código. Armazene tokens usando o armazenamento seguro fornecido pela plataforma cliente.
O token de acesso é emitido para o recurso, não para o cliente CIMD. O cliente usa o token para chamar o recurso protegido da mesma forma que outro cliente OAuth.
Solucionar falhas comuns
| Failure | O que verificar |
|---|---|
| O documento de metadados não pode ser recuperado | Confirme se a URL possa ser acessada publicamente por HTTPS, retorne uma resposta bem-sucedida diretamente e não redirecione. |
| A ID do cliente é rejeitada | Confirme se o client_id, a URL de recuperação e o client_id do documento são idênticos. |
| O URI de redirecionamento é rejeitado | Compare o URI de redirecionamento solicitado com o documento, incluindo esquema, host, caminho, porta, maiúsculas e minúsculas e barra à direita. |
| O usuário não pode aprovar o aplicativo cliente | Examine a política de consentimento do usuário do locatário e se as permissões solicitadas exigem consentimento do administrador. |
| O token tem o audience errado | Envie a URL canônica do servidor MCP como resource e solicite um escopo exposto por esse recurso. |
| Já existe um cliente com essa URL | Use novamente a identidade local existente do tenant. Somente uma identidade com suporte CIMD para uma URL canônica pode existir em um locatário. |
| O cliente parou de funcionar após uma alteração de URL | Restaure a URL original ou cadastre a nova URL como uma nova identidade e obtenha o consentimento novamente. |