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 uma aplicação. Este método, juntamente com removeKey, pode ser utilizado por uma aplicação para automatizar a implementação das chaves a expirar.
Observação
Pode continuar a utilizar as operações Criar aplicação e Atualizar aplicação para adicionar e atualizar credenciais de chave para qualquer aplicação com ou sem o contexto de um utilizador.
Só deve fornecer o valor da chave pública ao adicionar uma credencial de certificado à sua aplicação. Adicionar um certificado de chave privada à sua aplicação corre o risco de comprometer a aplicação.
Como parte da validação do pedido para este método, é verificada uma prova de posse de uma chave existente antes de a ação poder ser executada.
As aplicações que não têm certificados válidos existentes (ainda não foram adicionados certificados ou todos os certificados expiraram), não poderão utilizar esta ação de serviço. Você pode usar a operação Atualizar aplicativo para executar uma atualização.
Esta API está disponível nas seguintes implementações de cloud nacionais.
| Serviço global |
US Government L4 |
US Government L5 (DOD) |
China operada pela 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissões
Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.
| Tipo de permissão |
Permissões com menos privilégios |
Permissões com privilégios superiores |
| Delegado (conta corporativa ou de estudante) |
Application.ReadWrite.All |
Directory.ReadWrite.All |
| Delegado (conta pessoal da Microsoft) |
Sem suporte. |
Sem suporte. |
| Application |
Application.ReadWrite.OwnedBy |
Application.ReadWrite.All, Directory.ReadWrite.All |
Observação
Uma aplicação não precisa de permissão específica para implementar as suas próprias chaves.
Importante
Em cenários delegados com contas escolares ou profissionais, o utilizador com sessão iniciada tem de ter uma função de Microsoft Entra suportada ou uma função personalizada com uma permissão de função suportada. As seguintes funções com menos privilégios são suportadas para esta operação.
- Um utilizador membro não administrador com permissões de utilizador predefinidas – para aplicações que possui
- Programador de Aplicações – para aplicações que possuem
- Administrador de Aplicativos de Nuvem
- Administrador de Aplicativos
Solicitação HTTP
Pode abordar a aplicação com o respetivo ID ou appId.
O id e o appId são referidos como o ID do Objeto e o ID da Aplicação (Cliente), respetivamente, nos registos de aplicações no centro de administração do Microsoft Entra.
POST /applications/{id}/addKey
POST /applications(appId='{appId}')/addKey
| 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 do pedido, forneça as seguintes propriedades necessárias.
| Propriedade |
Tipo |
Descrição |
| keyCredential |
keyCredential |
A nova credencial da chave da aplicação a adicionar. O tipo, a utilização e a chave são propriedades necessárias para esta utilização. Os tipos de chave suportados são:
-
AsymmetricX509Cert: a utilização tem de ser Verify. -
X509CertAndPassword: a utilização tem de ser Sign
|
| passwordCredential |
passwordCredential |
Só é necessário definir secretText que deve conter a palavra-passe da chave. Esta propriedade é necessária apenas para chaves do tipo X509CertAndPassword. Defina-o para o null contrário. |
| prova |
Cadeia de caracteres |
Um token JWT autoassinado utilizado 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: o público tem de ser
00000002-0000-0000-c000-000000000000. -
iss: O emissor tem de ser o ID da aplicação que inicia o pedido.
-
nbf: Não antes do tempo.
-
exp: O tempo de expiração deve ser o valor de nbf + 10 minutos.
Para obter os passos para gerar este token de prova de posse, veja Gerar tokens de prova de posse para chaves sem interrupção. Para obter mais informações sobre os tipos de afirmação, veja Payload de afirmações. |
Resposta
Se for bem-sucedido, este método devolve um 200 OK código de resposta e um novo objeto keyCredential no corpo da resposta.
Exemplos
Exemplo 1: Adicionar uma nova credencial de chave a uma aplicação
Solicitação
O exemplo a seguir mostra uma solicitação.
POST https://graph.microsoft.com/beta/applications/{id}/addKey
Content-type: application/json
{
"keyCredential": {
"type": "AsymmetricX509Cert",
"usage": "Verify",
"key": "MIIDYDCCAki..."
},
"passwordCredential": null,
"proof":"eyJ0eXAiOiJ..."
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Applications.Item.AddKey;
using Microsoft.Graph.Beta.Models;
var requestBody = new AddKeyPostRequestBody
{
KeyCredential = new KeyCredential
{
Type = "AsymmetricX509Cert",
Usage = "Verify",
Key = Convert.FromBase64String("MIIDYDCCAki..."),
},
PasswordCredential = null,
Proof = "eyJ0eXAiOiJ...",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].AddKey.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphapplications "github.com/microsoftgraph/msgraph-beta-sdk-go/applications"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphapplications.NewAddKeyPostRequestBody()
keyCredential := graphmodels.NewKeyCredential()
type := "AsymmetricX509Cert"
keyCredential.SetType(&type)
usage := "Verify"
keyCredential.SetUsage(&usage)
key := []byte("mIIDYDCCAki...")
keyCredential.SetKey(&key)
requestBody.SetKeyCredential(keyCredential)
passwordCredential := null
requestBody.SetPasswordCredential(&passwordCredential)
proof := "eyJ0eXAiOiJ..."
requestBody.SetProof(&proof)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
addKey, err := graphClient.Applications().ByApplicationId("application-id").AddKey().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.applications.item.addkey.AddKeyPostRequestBody addKeyPostRequestBody = new com.microsoft.graph.beta.applications.item.addkey.AddKeyPostRequestBody();
KeyCredential keyCredential = new KeyCredential();
keyCredential.setType("AsymmetricX509Cert");
keyCredential.setUsage("Verify");
byte[] key = Base64.getDecoder().decode("MIIDYDCCAki...");
keyCredential.setKey(key);
addKeyPostRequestBody.setKeyCredential(keyCredential);
addKeyPostRequestBody.setPasswordCredential(null);
addKeyPostRequestBody.setProof("eyJ0eXAiOiJ...");
KeyCredential result = graphClient.applications().byApplicationId("{application-id}").addKey().post(addKeyPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const keyCredential = {
keyCredential: {
type: 'AsymmetricX509Cert',
usage: 'Verify',
key: 'MIIDYDCCAki...'
},
passwordCredential: null,
proof: 'eyJ0eXAiOiJ...'
};
await client.api('/applications/{id}/addKey')
.version('beta')
.post(keyCredential);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Applications\Item\AddKey\AddKeyPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\KeyCredential;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new AddKeyPostRequestBody();
$keyCredential = new KeyCredential();
$keyCredential->setType('AsymmetricX509Cert');
$keyCredential->setUsage('Verify');
$keyCredential->setKey(\GuzzleHttp\Psr7\Utils::streamFor(base64_decode('MIIDYDCCAki...')));
$requestBody->setKeyCredential($keyCredential);
$requestBody->setPasswordCredential(null);
$requestBody->setProof('eyJ0eXAiOiJ...');
$result = $graphServiceClient->applications()->byApplicationId('application-id')->addKey()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Applications
$params = @{
keyCredential = @{
type = "AsymmetricX509Cert"
usage = "Verify"
key = [System.Text.Encoding]::ASCII.GetBytes("MIIDYDCCAki...")
}
passwordCredential = $null
proof = "eyJ0eXAiOiJ..."
}
Add-MgBetaApplicationKey -ApplicationId $applicationId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.applications.item.add_key.add_key_post_request_body import AddKeyPostRequestBody
from msgraph_beta.generated.models.key_credential import KeyCredential
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = AddKeyPostRequestBody(
key_credential = KeyCredential(
type = "AsymmetricX509Cert",
usage = "Verify",
key = base64.urlsafe_b64decode("MIIDYDCCAki..."),
),
password_credential = None,
proof = "eyJ0eXAiOiJ...",
)
result = await graph_client.applications.by_application_id('application-id').add_key.post(request_body)
Resposta
O exemplo a seguir mostra a resposta.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.keyCredential"
}
Exemplo 2: Adicionar uma credencial de chave e uma palavra-passe associada para a chave
Solicitação
O exemplo a seguir mostra uma solicitação.
POST https://graph.microsoft.com/beta/applications/{id}/addKey
Content-type: application/json
{
"keyCredential": {
"type": "X509CertAndPassword",
"usage": "Sign",
"key": "MIIDYDCCAki..."
},
"passwordCredential": {
"secretText": "MKTr0w1..."
},
"proof":"eyJ0eXAiOiJ..."
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Applications.Item.AddKey;
using Microsoft.Graph.Beta.Models;
var requestBody = new AddKeyPostRequestBody
{
KeyCredential = new KeyCredential
{
Type = "X509CertAndPassword",
Usage = "Sign",
Key = Convert.FromBase64String("MIIDYDCCAki..."),
},
PasswordCredential = new PasswordCredential
{
SecretText = "MKTr0w1...",
},
Proof = "eyJ0eXAiOiJ...",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].AddKey.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphapplications "github.com/microsoftgraph/msgraph-beta-sdk-go/applications"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphapplications.NewAddKeyPostRequestBody()
keyCredential := graphmodels.NewKeyCredential()
type := "X509CertAndPassword"
keyCredential.SetType(&type)
usage := "Sign"
keyCredential.SetUsage(&usage)
key := []byte("mIIDYDCCAki...")
keyCredential.SetKey(&key)
requestBody.SetKeyCredential(keyCredential)
passwordCredential := graphmodels.NewPasswordCredential()
secretText := "MKTr0w1..."
passwordCredential.SetSecretText(&secretText)
requestBody.SetPasswordCredential(passwordCredential)
proof := "eyJ0eXAiOiJ..."
requestBody.SetProof(&proof)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
addKey, err := graphClient.Applications().ByApplicationId("application-id").AddKey().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.applications.item.addkey.AddKeyPostRequestBody addKeyPostRequestBody = new com.microsoft.graph.beta.applications.item.addkey.AddKeyPostRequestBody();
KeyCredential keyCredential = new KeyCredential();
keyCredential.setType("X509CertAndPassword");
keyCredential.setUsage("Sign");
byte[] key = Base64.getDecoder().decode("MIIDYDCCAki...");
keyCredential.setKey(key);
addKeyPostRequestBody.setKeyCredential(keyCredential);
PasswordCredential passwordCredential = new PasswordCredential();
passwordCredential.setSecretText("MKTr0w1...");
addKeyPostRequestBody.setPasswordCredential(passwordCredential);
addKeyPostRequestBody.setProof("eyJ0eXAiOiJ...");
KeyCredential result = graphClient.applications().byApplicationId("{application-id}").addKey().post(addKeyPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const keyCredential = {
keyCredential: {
type: 'X509CertAndPassword',
usage: 'Sign',
key: 'MIIDYDCCAki...'
},
passwordCredential: {
secretText: 'MKTr0w1...'
},
proof: 'eyJ0eXAiOiJ...'
};
await client.api('/applications/{id}/addKey')
.version('beta')
.post(keyCredential);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Applications\Item\AddKey\AddKeyPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\KeyCredential;
use Microsoft\Graph\Beta\Generated\Models\PasswordCredential;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new AddKeyPostRequestBody();
$keyCredential = new KeyCredential();
$keyCredential->setType('X509CertAndPassword');
$keyCredential->setUsage('Sign');
$keyCredential->setKey(\GuzzleHttp\Psr7\Utils::streamFor(base64_decode('MIIDYDCCAki...')));
$requestBody->setKeyCredential($keyCredential);
$passwordCredential = new PasswordCredential();
$passwordCredential->setSecretText('MKTr0w1...');
$requestBody->setPasswordCredential($passwordCredential);
$requestBody->setProof('eyJ0eXAiOiJ...');
$result = $graphServiceClient->applications()->byApplicationId('application-id')->addKey()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Applications
$params = @{
keyCredential = @{
type = "X509CertAndPassword"
usage = "Sign"
key = [System.Text.Encoding]::ASCII.GetBytes("MIIDYDCCAki...")
}
passwordCredential = @{
secretText = "MKTr0w1..."
}
proof = "eyJ0eXAiOiJ..."
}
Add-MgBetaApplicationKey -ApplicationId $applicationId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.applications.item.add_key.add_key_post_request_body import AddKeyPostRequestBody
from msgraph_beta.generated.models.key_credential import KeyCredential
from msgraph_beta.generated.models.password_credential import PasswordCredential
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = AddKeyPostRequestBody(
key_credential = KeyCredential(
type = "X509CertAndPassword",
usage = "Sign",
key = base64.urlsafe_b64decode("MIIDYDCCAki..."),
),
password_credential = PasswordCredential(
secret_text = "MKTr0w1...",
),
proof = "eyJ0eXAiOiJ...",
)
result = await graph_client.applications.by_application_id('application-id').add_key.post(request_body)
Resposta
O exemplo a seguir mostra a resposta.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.keyCredential"
}