Compartilhar via

Gerir aplicações Microsoft Entra com o Microsoft Graph

Microsoft Entra aplicações permitem o acesso seguro aos recursos na cloud da Microsoft. O Microsoft Graph fornece um ponto final de API unificado que lhe permite criar, configurar e gerir programaticamente estas aplicações e os respetivos principais de serviço associados. Este artigo mostra-lhe como automatizar tarefas comuns de gestão de aplicações com o Microsoft Graph, incluindo registar aplicações, atualizar propriedades, atribuir permissões e gerir credenciais.

Pré-requisitos

  • Para testar as operações da API, inicie sessão no Graph Explorer com uma conta que lhe permite criar e gerir aplicações no seu inquilino.

Registar uma aplicação no Microsoft Entra ID

Crie uma aplicação ao especificar a propriedade displayName necessária. O pedido utiliza valores predefinidos para outras propriedades.

Permissão delegada com menos privilégios: Application.ReadWrite.All.

POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
  "displayName": "My application"
}

O pedido devolve uma 201 Created resposta com o objeto da aplicação no corpo da resposta. A aplicação obtém um ID exclusivo para aplicações no inquilino e um appId globalmente exclusivo no ecossistema Microsoft Entra ID.

Criar um principal de serviço para uma aplicação

Permissão delegada com menos privilégios: Application.ReadWrite.All.

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
  "appId": "fc876dd1-6bcb-4304-b9b6-18ddf1526b62"
}

O pedido devolve uma 201 Created resposta que inclui o objeto do principal de serviço no corpo da resposta.

Endereçar uma aplicação ou um objeto de principal de serviço

Referenciar uma aplicação ou um principal de serviço pelo respetivo ID. Esta sintaxe suporta os métodos GET, PATCH e DELETE HTTP.

https://graph.microsoft.com/v1.0/applications/{applicationObjectId}
https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalObjectId}

Referencie uma aplicação ou um principal de serviço pelo respetivo appId. Esta sintaxe suporta os métodos GET, PATCH e DELETE HTTP.

https://graph.microsoft.com/v1.0/applications(appId='appId')
https://graph.microsoft.com/v1.0/servicePrincipals(appId='appId')

Resolva um objeto de aplicação através do respetivo uniqueName com o método PATCH. Utilize esta propriedade para criar uma aplicação com o nome exclusivo, caso não exista, ou atualize-a se existir. Esta operação chama-se Upsert.

PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='{uniqueName}')
Content-Type: application/json
Prefer: create-if-missing

{
  "displayName": "Display name"
}

Configurar outras propriedades básicas para a sua aplicação

Permissão delegada com menos privilégios: Application.ReadWrite.All.

Configure estas propriedades básicas para a sua aplicação:

  • Adicionar etiquetas para categorização (utilize HideApp para ocultar a aplicação do Meus Aplicativos e do Iniciador do Microsoft 365)
  • Adicionar um logótipo, termos de serviço e declaração de privacidade
  • Armazenar informações de contacto
PATCH https://graph.microsoft.com/v1.0/applications/0d0021e2-eaab-4b9f-a5ad-38c55337d63e/
Content-type: application/json

{
  "tags": [
      "HR",
      "Payroll",
      "HideApp"
  ],
  "info": {
      "logoUrl": "https://cdn.contoso.com/photo/2016/03/21/23/25/link-1271843_1280.png",
      "marketingUrl": "https://www.contoso.com/app/marketing",
      "privacyStatementUrl": "https://www.contoso.com/app/privacy",
      "supportUrl": "https://www.contoso.com/app/support",
      "termsOfServiceUrl": "https://www.contoso.com/app/termsofservice"
  },
  "web": {
      "homePageUrl": "https://www.contoso.com/",
      "logoutUrl": "https://www.contoso.com/frontchannel_logout",
      "redirectUris": [
          "https://localhost"
      ]
  },
  "serviceManagementReference": "Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;"
}

Restringir o início de sessão apenas aos utilizadores atribuídos a todas as funções na aplicação.

Permissão delegada com menos privilégios: Application.ReadWrite.All.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/89473e09-0737-41a1-a0c3-1418d6908bcd

{
    "appRoleAssignmentRequired": true
}

Atribuir permissões a uma aplicação

Atribua permissões através do Microsoft Graph ao atualizar a propriedade requiredResourceAccess do objeto da aplicação. Este método é uma alternativa programática à utilização do centro de administração do Microsoft Entra. Inclua as permissões existentes e novas para evitar a remoção de permissões atribuídas, mas não concedidas.

A atribuição de permissões não as concede . Conceda consentimento do administrador no centro de administração do Microsoft Entra ou através de programação com as APIs do Microsoft Graph.

Permissão delegada com menos privilégios: Application.ReadWrite.All.

PATCH https://graph.microsoft.com/v1.0/applications/581088ba-83c5-4975-b8af-11d2d7a76e98
Content-Type: application/json

{
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        },
        {
          "id": "3afa6a7d-9b1a-42eb-948e-1650a849e176",
          "type": "Role"
        }
      ]
    }
  ]
}

Criar funções de aplicação

Criar funções de aplicação num objeto de aplicação

Para adicionar ou atualizar funções de aplicações, inclua todas as funções existentes no seu pedido. Se omitir funções existentes, estas serão removidas.

PATCH https://graph.microsoft.com/v1.0/applications/bbd46130-e957-4c38-a116-d4d02afd1057
Content-Type: application/json

{
  "appRoles": [
    {
      "allowedMemberTypes": [
          "User",
          "Application"
      ],
      "description": "Survey.Read",
      "displayName": "Survey.Read",
      "id": "7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0",
      "isEnabled": false,
      "origin": "Application",
      "value": "Survey.Read"
    }
  ]
}

Gerir proprietários

Identificar principais de serviço sem proprietário ou com apenas um proprietário

Permissão delegada com menos privilégios: Application.ReadWrite.All.

Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual porque $count está na solicitação. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Este pedido também devolve a contagem das aplicações que correspondem à condição de filtro.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=owners/$count eq 0 or owners/$count eq 1&$count=true
ConsistencyLevel: eventual

Atribuir um proprietário a uma aplicação

Permissão delegada com menos privilégios: Application.ReadWrite.All.

No pedido seguinte, 8afc02cb-4d62-4dba-b536-9f6d73e9be26 encontra-se o ID de objeto de um utilizador ou principal de serviço.

POST https://graph.microsoft.com/v1.0/applications/7b45cf6d-9083-4eb2-92c4-a7e090f1fc40/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

Atribuir um proprietário a um principal de serviço

Permissão delegada com menos privilégios: Application.ReadWrite.All.

O pedido seguinte referencia o principal de serviço com o respetivo appId. Em alternativa, pode referenciá-lo com o ID de objeto no padrão ../servicePrincipals/{object ID}/owners/$ref. dddddddd-9999-0000-1111-eeeeeeeeeeee é o ID de objeto de um utilizador ou principal de serviço.

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='00001111-aaaa-2222-bbbb-3333cccc4444')/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/dddddddd-9999-0000-1111-eeeeeeeeeeee"
}

Bloquear propriedades confidenciais para principais de serviço

Utilize a funcionalidade de bloqueio de instância de aplicação para proteger as propriedades confidenciais dos principais de serviço contra alterações não autorizadas. O Yo pode bloquear as seguintes propriedades:

  • keyCredentials em que o tipo de utilização é Sign ou Verify.
  • passwordCredentials em que o tipo de utilização é Sign ou Verify.
  • propriedade tokenEncryptionKeyId .

Pode gerir a funcionalidade de bloqueio da instância da aplicação através da propriedade servicePrincipalLockConfiguration do objeto de aplicação da aplicação multi-inquilino.

Para bloquear todas as propriedades confidenciais de um principal de serviço

Quando isEnabled e allProperties está definido como true, mesmo que outras propriedades do objeto servicePrincipalLockConfiguration sejam null, todas as propriedades confidenciais do principal de serviço estão bloqueadas.

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "allProperties": true
    }
}

Para bloquear propriedades confidenciais específicas de um principal de serviço

O exemplo seguinte bloqueia as propriedades keyCredentials e passwordCredentials do principal de serviço e ativa a funcionalidade de bloqueio da instância da aplicação.

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "credentialsWithUsageSign": true,
        "credentialsWithUsageVerify": true
    }
}

Configurar autoridades de certificação fidedignas para aplicações

Pode restringir a utilização de credenciais de certificado para aplicações no seu inquilino apenas para os certificados emitidos pelas autoridades de certificação fidedignas. Esta política é imposta quando adiciona um certificado a uma aplicação e não afeta os certificados existentes, a menos que sejam rodados. Quando uma aplicação tenta rodar as respetivas credenciais de certificado, passa pela avaliação da política para garantir que as credenciais adicionadas estão em conformidade com a restrição de autoridade de certificação fidedigna.

Passo 1: Criar uma cadeia de certificados de fidedignidade

Permissão delegada com menos privilégios: AppCertTrustConfiguration.Read.All função de Microsoft Entra com privilégios mínimos:Application Administrator

POST https://graph.microsoft.com/beta/certificateAuthorities/certificateBasedApplicationConfigurations

{
    "displayName": "Trusted Certificate Chain of Trust for Contoso",
    "description": "The Trusted Certificate Chain of Trust containing a certificate chain used by app policy, to only allow application certificates from selected issuer.",
    "trustedCertificateAuthorities": [
        {
            "isRootAuthority": true,
            "certificate": "MIIFVjCCAz6gAwIBAgIQJdrL...UyNDIyNTcwM1owPDE …="
        },
        {
            "isRootAuthority": false,
            "certificate": QAAAAAAWjABAQsFADA8M...UyNDIyNTcwM1o …="
        }
    ]
}

A solicitação retorna uma resposta 200 OK. A resposta inclui o ID da cadeia de certificados do objeto de fidedignidade. Suponha que o ID é eec5ba11-2fc0-4113-83a2-ed986ed13743 utilizado no Passo 2.

Passo 2: atribuir a cadeia de certificados de confiança a uma política de gestão de aplicações

O exemplo seguinte configura uma política para garantir que apenas os certificados emitidos pela autoridade de certificação intermédia definida no passo anterior podem ser adicionados a aplicações no inquilino. O objeto applicationRestrictions>keyCredentials define um restrictionType com o valor trustedCertificateAuthority, que referencia o ID que foi criado. Uma vez que esta política é aplicada à política de gestão de aplicações ao nível do inquilino predefinida, é imposta para todas as aplicações criadas no inquilino e rejeita tentativas de adicionar certificados não conformes como parte das credenciais de certificado de uma aplicação.

Esta política garante que apenas os certificados da autoridade de certificação intermédia especificada podem ser adicionados às aplicações. O objeto applicationRestrictions>keyCredentials define um restrictionType como trustedCertificateAuthority, referenciando o ID criado. Esta política aplica-se a todas as aplicações no inquilino, rejeitando quaisquer certificados não conformes.

Permissão delegada com menos privilégios: Policy.Read.ApplicationConfiguration função de Microsoft Entra com privilégios mínimos:Security Administrator

PATCH https://graph.microsoft.com/v1.0/policies/defaultAppManagementPolicy

{
  "id": "d015220e-9789-4e8e-bbcc-270fe419229d",
  "description": "Lorem ipsum",
  "displayName": "Credential management policy",
  "isEnabled": true,
  "applicationRestrictions": {
    "passwordCredentials": [
      {
        "restrictionType": "passwordLifetime",
        "maxLifetime": "P14D",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T07:00:00Z"
      }
    ],
    "keyCredentials": [
      {
        "restrictionType": "certificateLifetime",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T10:37:00Z",
        "maxLifetime": "P90D"
      },
      {
        "restrictionType": "trustedCertificateAuthority",
        "certificateBasedApplicationConfigurationIds": [
          "eec5ba11-2fc0-4113-83a2-ed986ed13743"
        ],
        "restrictForAppsCreatedAfterDateTime": "2019-10-19T10:37:00Z"
      }
    ]
  }
}

Conteúdo relacionado

  • Last updated on