Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Namespace: microsoft.graph
Importante
As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.
Crie um novo objeto federatedIdentityCredential para um aplicativo ou um agentIdentityBlueprint se ele não existir ou atualize as propriedades de um objeto federatedIdentityCredential existente.
Ao configurar uma relação de confiança entre o registro do aplicativo Microsoft Entra ou agentIdentityBlueprint e o provedor de identidade da plataforma de computação, você pode usar tokens emitidos por essa plataforma para autenticar com a plataforma de identidade da Microsoft e chamar APIs no ecossistema da Microsoft. No máximo 20 objetos podem ser adicionados a um aplicativo ou agentIdentityBlueprint.
Essa API está disponível nas seguintes implantações de nuvem nacional.
| Serviço global | Governo dos EUA L4 | US Government L5 (DOD) | China operada pela 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.
Permissões para um aplicativo
| Tipo de permissão | Permissões menos privilegiadas | Permissões com privilégios mais elevados |
|---|---|---|
| Delegado (conta corporativa ou de estudante) | Application.ReadWrite.All | Indisponível. |
| Delegado (conta pessoal da Microsoft) | Application.ReadWrite.All | Indisponível. |
| Application | Application.ReadWrite.OwnedBy | Application.ReadWrite.All |
Importante
Para acesso delegado usando contas corporativas ou de estudante, o usuário conectado deve receber uma função do Microsoft Entra com suporte ou uma função personalizada que conceda as permissões necessárias para esta operação. Esta operação dá suporte às seguintes funções internas, que fornecem apenas o menor privilégio necessário:
- Um usuário membro não administrador com permissões de usuário padrão - para aplicativos que possuem
- Desenvolvedor de Aplicativos - para aplicativos que possuem
- Administrador de Aplicativos de Nuvem
- Administrador de Aplicativos
Permissões para um agentIdentityBlueprint
| Tipo de permissão | Permissão com privilégios mínimos | Permissões com privilégios mais elevados |
|---|---|---|
| Delegado (conta corporativa ou de estudante) | AgentIdentityBlueprint.ReadWrite.All | Directory.ReadWrite.All |
| Delegado (conta pessoal da Microsoft) | Sem suporte. | Sem suporte. |
| Application | AgentIdentityBlueprint.ReadWrite.All | Directory.ReadWrite.All |
Importante
- Uma entidade de segurança que cria um blueprint de identidade de agente ou uma entidade de segurança de plano é automaticamente atribuída como proprietária.
- Os proprietários podem criar e modificar identidades de agente associadas a um blueprint que possuem sem receber uma função de ID de agente.
- Para que os não proprietários chamem essa API em cenários delegados usando contas corporativas ou de estudante, o administrador deve receber uma função do Microsoft Entra com suporte. Esta operação dá suporte à seguinte função interna com privilégios mínimos:
Solicitação HTTP
Para um aplicativo:
- Você pode abordar o aplicativo usando sua id ou appId. id e appId são chamados de ID do Objeto e ID do Aplicativo (Cliente), respectivamente, em registros de aplicativo no centro de administração do Microsoft Entra.
PATCH /applications/{id}/federatedIdentityCredentials(name='{name}')
PATCH /applications(appId='{appId}')/federatedIdentityCredentials(name='{name}')
Para um agentIdentityBlueprint:
PATCH /applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials(name='{name}')
Cabeçalhos de solicitação
| Nome | Descrição |
|---|---|
| Autorização | {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização. |
| Content-Type | application/json. Obrigatório. |
| Preferir |
create-if-missing. Necessário para o comportamento de upsert, caso contrário, a solicitação será tratada como uma operação de atualização. |
Corpo da solicitação
No corpo da solicitação, forneça uma representação JSON do objeto federatedIdentityCredential .
A tabela a seguir lista as propriedades necessárias ao criar o federatedIdentityCredential. Observe que a propriedade name é necessária como parte da URL de solicitação.
| Propriedade | Tipo | Descrição |
|---|---|---|
| Públicos-alvo | String collection | A audiência que pode aparecer no token externo. Esse campo é obrigatório e deve ser definido como api://AzureADTokenExchange para o Microsoft Entra ID. Ele diz o que a aud plataforma de identidade da Microsoft deve aceitar na declaração no token de entrada. Esse valor representa o Microsoft Entra ID em seu provedor de identidade externo e não tem valor fixo entre provedores de identidade – talvez seja necessário criar um novo registro de aplicativo em seu provedor de identidade para servir como o público-alvo desse token. Este campo só pode aceitar um único valor e tem um limite de 600 caracteres. Obrigatório. |
| claimsMatchingExpression | federatedIdentityExpression | Anulável. O padrão é null se não estiver definido. Permite o uso de declarações que correspondem a expressões em declarações especificadas. Se claimsMatchingExpression estiver definido, o assunto deverá ser null. Para obter a lista de sintaxe de expressão e declarações com suporte, visite a referência FIC flexível. |
| do emissor | Cadeia de caracteres | URL do provedor de identidade externo e deve corresponder à declaração do emissor do token externo que está sendo trocado. A combinação dos valores de emissor e assunto deve ser exclusiva no aplicativo. Tem um limite de 600 caracteres. Obrigatório. |
| assunto | Cadeia de caracteres | Anulável. O padrão é null se não estiver definido. O identificador da carga de trabalho de software externo no provedor de identidade externo. Assim como o valor de audiência, ele não tem um formato fixo, pois cada provedor de identidade usa o seu próprio: às vezes um GUID, às vezes um identificador delimitado por dois pontos, às vezes cadeias de caracteres arbitrárias. O valor aqui deve corresponder à declaração sub dentro do token apresentado ao Microsoft Entra ID. Tem um limite de 600 caracteres. A combinação de emissor e assunto deve ser exclusiva no aplicativo. Se o assunto for definido, claimsMatchingExpression deverá ser null. |
Resposta
Se for bem-sucedido, se um objeto de aplicativo com nome não existir, esse método retornará um código de 201 Created resposta e um novo objeto federatedIdentityCredential no corpo da resposta.
Se já existe um objeto de aplicativo com nome , esse método atualiza o objeto federatedIdentityCredential e retorna um código de 204 No Content resposta.
Exemplos
Exemplo 1: Criar uma nova federatedIdentityCredential para um aplicativo se ele não existir
O exemplo a seguir cria uma federatedIdentityCredential porque uma federatedIdentityCredential com o valor de nome especificado não existe.
Solicitação
O exemplo a seguir mostra uma solicitação.
PATCH https://graph.microsoft.com/beta/applications(uniqueName='app-65278')/federatedIdentityCredentials(name='fic01-app-65278')
Content-Type: application/json
{
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"audiences": [
"api://AzureADTokenExchange"
]
}
Resposta
O exemplo a seguir mostra a resposta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#applications('bcd7c908-1c4d-4d48-93ee-ff38349a75c8')/federatedIdentityCredentials/$entity",
"id": "d9b7bf1e-429e-4678-8132-9b00c9846cc4",
"name": "testing02fic01-app-65278",
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"description": null,
"audiences": [
"api://AzureADTokenExchange"
]
}
Exemplo 2: Atualizar uma federatedIdentityCredential existente para um aplicativo
O exemplo a seguir atualiza o federatedIdentityCredential porque existe um federatedIdentityCredential com o valor de nome especificado.
Solicitação
O exemplo a seguir mostra uma solicitação.
PATCH https://graph.microsoft.com/beta/applications(uniqueName='app-65278')/federatedIdentityCredentials(name='fic01-app-65278')
Content-Type: application/json
Prefer: create-if-missing
{
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"audiences": [
"api://AzureADTokenExchange"
]
}
Resposta
O exemplo a seguir mostra a resposta.
HTTP/1.1 204 No Content
Exemplo 3: Criar uma nova federatedIdentityCredential para um agentIdentityBlueprint se ela não existir
O exemplo a seguir cria um federatedIdentityCredential para um agentIdentityBlueprint porque um federatedIdentityCredential com o valor de nome especificado não existe.
Solicitação
O exemplo a seguir mostra uma solicitação.
PATCH https://graph.microsoft.com/beta/applications(uniqueName='app-65278')/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials(name='fic01-app-65278')
Content-Type: application/json
{
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"audiences": [
"api://AzureADTokenExchange"
]
}
Resposta
O exemplo a seguir mostra a resposta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#applications('bcd7c908-1c4d-4d48-93ee-ff38349a75c8')/federatedIdentityCredentials/$entity",
"id": "d9b7bf1e-429e-4678-8132-9b00c9846cc4",
"name": "testing02fic01-app-65278",
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"description": null,
"audiences": [
"api://AzureADTokenExchange"
]
}