agentIdentityBlueprint: addKey

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.

Adicione uma credencial de chave a um agentIdentityBlueprint. Esse método, juntamente com removeKey, pode ser usado para automatizar a rolagem de suas chaves expiradas.

Observação

Você só deve fornecer o valor da chave pública ao adicionar uma credencial de certificado ao seu aplicativo. Adicionar um certificado de chave privada ao seu aplicativo corre o risco de comprometer o aplicativo.

Como parte da validação de solicitação para esse método, uma prova de posse de uma chave existente é verificada antes que a ação possa ser executada.

Os blueprints de identidade do agente que não têm certificados válidos existentes (nenhum certificado foi adicionado ainda ou todos os certificados expiraram) não poderão usar essa ação de serviço. Em vez disso, você pode usar a operação de blueprint de identidade do agente de atualização para executar uma atualização.

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.

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.AddRemoveCreds.All AgentIdentityBlueprint.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.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

POST /applications/{id}/microsoft.graph.agentIdentityBlueprint/addKey

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.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON dos parâmetros. A tabela a seguir lista os parâmetros necessários quando você chama essa ação.

Propriedade Tipo Descrição
keyCredential keyCredential A nova credencial de chave do aplicativo a ser adicionada. O tipo, o uso e a chave são propriedades obrigatórias para esse uso. Os principais tipos de chaves com suporte são:
  • AsymmetricX509Cert: o uso deve ser Verify.
  • X509CertAndPassword: O uso deve ser Sign
passwordCredential passwordCredential Somente secretText é necessário definir o que deve conter a senha da chave. Esta propriedade é necessária apenas para chaves do tipo X509CertAndPassword. Defina-a como null outra forma.
à prova Cadeia de caracteres Um token JWT autoassinado usado como prova de posse das chaves existentes. Esse token de JWT deve ser assinado usando a chave privada de um dos certificados válidos existentes do aplicativo. O token deve conter os seguintes argumentos:
  • aud: A audiência precisa ser 00000002-0000-0000-c000-000000000000.
  • iss: O emissor precisa ser a ID do aplicativo que inicia a solicitação.
  • nbf: Não antes do tempo.
  • exp: O tempo de expiração deve ser o valor de nbf + 10 minutos.

Para ver as etapas para gerar esse token de prova de posse, consulte Geração de tokens de prova de posse para chaves de rolagem. Para obter mais informações sobre os tipos de declaração, consulte Carga de declarações.

Resposta

Se for bem-sucedida, essa ação retornará um código de 200 OK resposta e uma keyCredential no corpo da resposta.

Exemplos

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/beta/applications/{id}/microsoft.graph.agentIdentityBlueprint/addKey
Content-Type: application/json

{
  "keyCredential": {
    "@odata.type": "microsoft.graph.keyCredential"
  },
  "passwordCredential": {
    "@odata.type": "microsoft.graph.passwordCredential"
  },
  "proof": "String"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": {
    "@odata.type": "microsoft.graph.keyCredential"
  }
}