Gerenciar aplicativos do Microsoft Entra usando o Microsoft Graph

Os aplicativos do Microsoft Entra permitem o acesso seguro a recursos na nuvem da Microsoft. O Microsoft Graph fornece um ponto de extremidade de API unificado que permite criar, configurar e gerenciar programaticamente esses aplicativos e suas entidades de serviço associadas. Este artigo mostra como automatizar tarefas comuns de gerenciamento de aplicativos com o Microsoft Graph, incluindo registro de aplicativos, atualização de propriedades, atribuição de permissões e gerenciamento de credenciais.

Pré-requisitos

  • Para testar as operações da API, entre no Graph Explorer com uma conta que permite criar e gerenciar aplicativos em seu locatário.

Registrar um aplicativo com o Microsoft Entra ID

Crie um aplicativo especificando a propriedade displayName necessária. A solicitação usa valores padrão para outras propriedades.

Permissão delegada com privilégios mínimos: Application.ReadWrite.All.

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

{
  "displayName": "My application"
}

A solicitação retorna uma 201 Created resposta com o objeto de aplicativo no corpo da resposta. O aplicativo obtém uma ID exclusiva para aplicativos no locatário e um appId globalmente exclusivo no ecossistema do Microsoft Entra ID.

Criar uma entidade de serviço para um aplicativo

Permissão delegada com privilégios mínimos: Application.ReadWrite.All.

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

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

A solicitação retorna uma 201 Created resposta que inclui o objeto da entidade de serviço no corpo da resposta.

Abordando um aplicativo ou um objeto de entidade de serviço

Faça referência a um aplicativo ou entidade de serviço por sua ID. Essa sintaxe é compatível com os métodos HTTP GET, PATCH e DELETE.

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

Faça referência a um aplicativo ou entidade de serviço por seu appId. Essa sintaxe é compatível com os métodos HTTP GET, PATCH e DELETE.

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

Endereçar um objeto de aplicativo por seu nome exclusivo usando o método PATCH. Use esta propriedade para criar um aplicativo com o nome exclusivo, se ele não existir, ou atualizá-lo, se existir. Essa operação é chamada de 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 seu aplicativo

Permissão delegada com privilégios mínimos: Application.ReadWrite.All.

Configure estas propriedades básicas para seu aplicativo:

  • Adicionar marcas para categorização (use HideApp para ocultar o aplicativo dos Meus Aplicativos e do Microsoft 365 Launcher)
  • Adicionar um logotipo, termos de serviço e política de privacidade
  • Informações de contato da loja
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;"
}

Restrinja a entrada somente aos usuários atribuídos a todas as funções no aplicativo.

Permissão delegada com privilégios mínimos: Application.ReadWrite.All.

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

{
    "appRoleAssignmentRequired": true
}

Atribuir permissões a um aplicativo

Atribua permissões por meio do Microsoft Graph atualizando a propriedade requiredResourceAccess do objeto do aplicativo. Esse método é uma alternativa programática para usar o centro de administração do Microsoft Entra. Inclua permissões novas e existentes para evitar remover permissões atribuídas, mas não concedidas.

Atribuir permissões não as concede . Conceda consentimento de administrador no centro de administração do Microsoft Entra ou programaticamente usando APIs do Microsoft Graph.

Permissão delegada com privilégios mínimos: 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 aplicativo

Criar funções de aplicativo em um objeto de aplicativo

Para adicionar ou atualizar funções de aplicativo, inclua todas as funções existentes em sua solicitação. Se você omitir as funções existentes, elas 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"
    }
  ]
}

Gerenciar proprietários

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

Permissão delegada com privilégios mínimos: 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 o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.

Essa solicitação também retorna a contagem dos aplicativos 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 um aplicativo

Permissão delegada com privilégios mínimos: Application.ReadWrite.All.

Na solicitação a seguir, 8afc02cb-4d62-4dba-b536-9f6d73e9be26 está a ID de objeto de um usuário ou entidade 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 uma entidade de serviço

Permissão delegada com privilégios mínimos: Application.ReadWrite.All.

A solicitação a seguir faz referência à entidade de serviço usando seu appId. Como alternativa, você pode referenciá-lo usando o ID do objeto no padrão ../servicePrincipals/{object ID}/owners/$ref. dddddddd-9999-0000-1111-eeeeeeeeeeee é a ID de objeto de um usuário ou entidade 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 sensíveis para entidades de serviço

Use o recurso de bloqueio de instância do aplicativo para proteger propriedades confidenciais de entidades de serviço contra alterações não autorizadas. Você pode bloquear as seguintes propriedades:

  • keyCredentials em que o tipo de uso é Sign ou Verify.
  • passwordCredentials em que o tipo de uso é Sign ou Verify.
  • tokenEncryptionKeyId .

Você gerencia o recurso de bloqueio de instância do aplicativo por meio da propriedade servicePrincipalLockConfiguration do objeto de aplicativo do aplicativo multilocatário.

Para bloquear todas as propriedades confidenciais de uma entidade de serviço

Quando isEnabled e allProperties for definido como true, mesmo que outras propriedades do objeto servicePrincipalLockConfiguration sejam null, todas as propriedades confidenciais da entidade de serviço serã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 uma entidade de serviço

O exemplo a seguir bloqueia as propriedades keyCredentials e passwordCredentials da entidade de serviço e habilita o recurso de bloqueio de instância do aplicativo.

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

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

Configurar autoridades de certificação confiáveis para aplicativos

Você pode restringir o uso de credenciais de certificado para aplicativos em seu locatário apenas para os certificados emitidos por autoridades de certificação confiáveis. Essa política é imposta quando você adiciona um certificado a um aplicativo e não afeta os certificados existentes, a menos que sejam girados. Quando um aplicativo tenta alternar suas credenciais de certificado, ele passa pela avaliação de política para garantir que as credenciais que estão sendo adicionadas estejam em conformidade com a restrição de autoridade de certificação confiável.

Etapa 1: Criar uma cadeia de certificados de confiança

Permissão delegada com privilégios mínimos: AppCertTrustConfiguration.Read.All Função do 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 a ID da cadeia de certificados do objeto de confiança. Suponha que a ID seja eec5ba11-2fc0-4113-83a2-ed986ed13743 usada na Etapa 2.

Etapa 2: atribuir a cadeia de certificados de confiança a uma política de gerenciamento de aplicativo

O exemplo a seguir configura uma política para garantir que somente os certificados emitidos pela autoridade de certificação intermediária definida na etapa anterior possam ser adicionados aos aplicativos no locatário. O objeto applicationRestrictions>keyCredentials define um restrictionType com o valor trustedCertificateAuthority, que faz referência à ID que foi criada. Como essa política é aplicada à política de gerenciamento de aplicativos padrão no nível do locatário, ela é imposta a todos os aplicativos criados no locatário e rejeita tentativas de adicionar certificados não compatíveis como parte das credenciais de certificado de um aplicativo.

Essa política garante que somente certificados da autoridade de certificação intermediária especificada possam ser adicionados aos aplicativos. O objeto keyCredentials applicationRestrictions> define um restrictionType para trustedCertificateAuthority, referenciando a ID criada. Essa política se aplica a todos os aplicativos no locatário, rejeitando certificados não compatíveis.

Permissão delegada com privilégios mínimos: Policy.Read.ApplicationConfiguration Função do 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