Compartilhar via

Upsert federatedIdentityCredential

  • Artigo

Namespace: microsoft.graph

Crie um novo objeto federatedIdentityCredential para um aplicativo se ele existir ou atualize as propriedades de um objeto federatedIdentityCredential existente. Ao configurar uma relação de confiança entre seu Microsoft Entra registro de aplicativo e o provedor de identidade para sua plataforma de computação, você pode usar tokens emitidos por essa plataforma para autenticar com plataforma de identidade da Microsoft e chamar APIs no ecossistema da Microsoft. No máximo 20 objetos podem ser adicionados a um aplicativo.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
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

Solicitação HTTP

Você pode abordar o aplicativo usando sua id ou appId. Id e appId são chamados de ID de 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}')

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 um comportamento upsert, caso contrário, a solicitação é 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 a federatedIdentityCredential. Observe que a propriedade name é necessária como parte da URL de solicitação.

Propriedade Tipo Descrição
Público String collection O público-alvo que pode aparecer no token externo. Esse campo é obrigatório e deve ser definido como api://AzureADTokenExchange para Microsoft Entra ID. Ele diz qual plataforma de identidade da Microsoft deve aceitar na declaração aud no token de entrada. Esse valor representa Microsoft Entra ID em seu provedor de identidade externo e não tem nenhum 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. Esse campo só pode aceitar um único valor e tem um limite de 600 caracteres. Obrigatório.
Emissor Cadeia de caracteres TThe URL do provedor de identidade externa e deve corresponder à declaração do emissor do token externo que está sendo trocado. A combinação dos valores do emissor e do assunto deve ser exclusiva no aplicativo. Ele tem um limite de 600 caracteres. Obrigatório.
assunto Cadeia de caracteres Obrigatório. O identificador da carga de trabalho de software externo no provedor de identidade externo. Como o valor de audiência, ele não tem formato fixo, pois cada provedor de identidade usa o seu próprio - às vezes um GUID, às vezes um identificador delimitado por cólon, às vezes cadeias de caracteres arbitrárias. O valor aqui deve corresponder à sub-declaração dentro do token apresentado a Microsoft Entra ID. Ele tem um limite de 600 caracteres. A combinação de emissor e assunto deve ser exclusiva no aplicativo.

Resposta

Se for bem-sucedido, se um objeto de aplicativo com nome não existir, esse método retornará um 201 Created código de resposta e um novo objeto federatedIdentityCredential no corpo da resposta.

Se um objeto de aplicativo com nome já existir, esse método atualizará o objeto federatedIdentityCredential e retornará um código de 204 No Content resposta.

Exemplos

Exemplo 1: criar uma nova federatedIdentityCredential se ela 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/v1.0/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/v1.0/$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 um federatedIdentityCredential existente

O exemplo a seguir atualiza a federatedIdentityCredential porque existe uma federatedIdentityCredential com o valor de nome especificado.

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/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