Registrar um aplicativo

  • 10 minutos

Exercício – Registrar um aplicativo

Para permitir que seu aplicativo entre com a ID externa do Microsoft Entra, você precisa registrar o aplicativo no diretório.

Observação

Você precisará ter pelo menos a função de diretório Desenvolvedor de Aplicativos para registrar um aplicativo.

Essa função é uma função privilegiada. Leia sobre as melhores práticas para trabalhar com funções privilegiadas.

Você tem comentários? Conte-nos como está indo seu projeto de prova de conceito. Gostaríamos muito de ouvir de você!

  1. Para registrar seu próprio aplicativo, entre no centro de administração do Microsoft Entra e navegue até Aplicativos>Registros de aplicativo. Em seguida, selecione + Novo registro.

    Captura de tela da folha Registros de aplicativo com um botão intitulado Novo registro realçado.

  2. Na página Registrar um aplicativo que aparece, insira um aplicativo significativo Name exibido aos usuários do aplicativo, por exemplo, Mercearia Woodgrove. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional. Para Plataforma, selecione a opção Web e insira o URI de redirecionamento do aplicativo. O URI de redirecionamento é o ponto de extremidade para o qual os usuários são redirecionados pela ID Externa do Microsoft Entra após a autenticação com a ID Externa do Microsoft Entra ser concluída.

    Captura de tela de Registrar uma folha de aplicativo com contas neste diretório organizacional realçada apenas para quem pode usar esse aplicativo ou acessar essa API? e o URI de redirecionamento é realçado e definido como Web, bem como a URL para onde redirecionar o usuário após a autenticação bem-sucedida.

  3. O painel Visão geral do aplicativo será exibido após o registro bem-sucedido. Grave a ID do aplicativo (cliente) que será usada no código-fonte do aplicativo.

    Captura de tela dos Registros de aplicativo com visão geral na navegação à esquerda realçada. A ID do aplicativo (cliente) também é realçada no Essentials.

  4. Para adicionar mais URIs de redirecionamento ou uma URL de logoff do canal frontal, em Gerenciar, selecione Autenticação. A URL de logoff do Canal frontal é onde enviamos uma solicitação para que o aplicativo desmarque os dados de sessão do usuário. Isso é necessário para que o logoff único funcione corretamente.

    Captura de tela da folha Autenticação em Registros de aplicativo com o URI realçado em URIs de Redirecionamento da Web, bem como a URL da URL de logoff do Canal frontal.

  5. Para que um aplicativo Web (cliente confidencial) adquira um token de acesso, ele precisa de uma credencial para provar sua identidade para o Microsoft Entra ID. Você pode adicionar certificados e segredos do cliente (uma cadeia de caracteres) ou credenciais de identidade federada como credenciais ao registro do aplicativo cliente confidencial. Para o site de compras, usaremos um certificado. Para adicionar um certificado, selecione Certificados e segredos>Certificados>Carregar certificado.

    Captura de tela da folha Certificados e segredos em Registros de aplicativo em que não há certificados e realça um botão intitulado Carregar certificado.

  6. Selecione os arquivos que deseja carregar. Ele precisa ser um dos seguintes tipos de arquivo: .cer, .pem ou .crt. Depois, selecione Adicionar.

    Captura de tela do painel Carregar certificado aberto à direita com o ícone de upload realçado para carregar o certificado.

  7. Nas etapas a seguir, você adicionará a permissão necessária para o aplicativo Web. Em Gerenciar, selecione Permissões de APIe, em seguida, selecione Adicionar uma permissão.

    Captura de tela das permissões de API em Registros de aplicativo com um botão intitulado Adicionar uma permissão realçada.

  8. Em Solicitar permissões de API, selecione a guia APIs da Microsoft e selecione Microsoft Graph.

    Captura de tela do painel Solicitar permissões de API aberto à direita com um grupo de opções intitulado Microsoft Graph realçado.

  9. Selecione a opção permissões delegadas. Em seguida, na seção Selecionar permissões pesquise e selecione permissões de openid e offline_access. Para concluir, selecione Adicionar permissões.

    Captura de tela do painel Solicitar permissões da API aberta à direita com um grupo de opções intitulado Permissões delegadas realçadas e permissões para offline_access e openid marcadas nas caixas de seleção abaixo.

  10. Neste ponto, você atribuiu as permissões corretamente. No entanto, como o locatário é um locatário externo, os próprios usuários consumidores não podem consentir com essas permissões. Você, como administrador, deve consentir com essas permissões em nome de todos os usuários do locatário: Selecione Fornecer o consentimento do administrador para <your tenant name>, em seguida selecione Sim.

    Captura de tela de um botão intitulado Fornecer o consentimento do administrador para Mercearia Woodgrove realçados na folha de permissões da API.

    Bom trabalho! Agora meu aplicativo está pronto para usar.

1. Registrar um aplicativo

Para registrar um aplicativo Web, use a solicitação do Microsoft Graph abaixo e substitua os valores a seguir.

  • Valor de displayName com o nome exibido do aplicativo. Por exemplo, Mercearia Woodgrove.

  • Valores do redirectUris com o URI de redirecionamento do aplicativo. Por exemplo, https://woodgrovedemo.com/signin-oidc. Também é possível usar https://www.jwt.ms/.

    POST https://graph.microsoft.com/v1.0/applications
{
    "displayName": "Woodgrove Groceries",
    "description": "Woodgrove Groceries live demo application",
    "signInAudience": "AzureADMyOrg",
    "api": {
        "acceptMappedClaims": true,
        "requestedAccessTokenVersion": 2
    },
    "requiredResourceAccess": [
        {
            "resourceAppId": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
            "resourceAccess": [
                {
                    "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
                    "type": "Scope"
                },
                {
                    "id": "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
                    "type": "Scope"
                }
            ]
        }
    ],
    "web": {
        "redirectUris": [
            "https://woodgrovedemo.com/signin-oidc"
        ],
        "implicitGrantSettings": {
            "enableAccessTokenIssuance": false,
            "enableIdTokenIssuance": false
        }
    }
}
1.1 Copie a ID do aplicativo

Na resposta, copie o valor de appId. Por exemplo:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "displayName": "Woodgrove Groceries",
    "description": "Woodgrove Groceries live demo application",
    ...
}

2. Criar uma entidade de serviço para seu aplicativo

Depois de registrar seu aplicativo, crie uma entidade de serviço. A chamada do Graph a seguir cria uma entidade de serviço. Substitua o {appId} pelo aplicativo appId da chamada anterior (não a ID do objeto).

POST https://graph.microsoft.com/v1.0/servicePrincipals
{
    "appId": "{appId}"
}
2.1 Copiar a ID da entidade de serviço

Na resposta, copie o valor de id. Por exemplo:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals/$entity",
    "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
    "displayName": "Woodgrove Groceries",
    "description": "Woodgrove Groceries live demo application",
    ...
}

Como o locatário é um locatário externo, os próprios usuários consumidores não podem consentir com essas permissões. Você, como administrador, deve consentir com essas permissões em nome de todos os usuários do locatário.

3.1 Obter a ID da entidade de serviço do Microsoft Graph

Execute a seguinte solicitação GET e copie a id da resposta:

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='22223333-cccc-4444-dddd-5555eeee6666')
{
    "id": "cccccccc-2222-3333-4444-dddddddddddd",
    "appDisplayName": "Microsoft Graph",
    "appId": "22223333-cccc-4444-dddd-5555eeee6666"
}
3.2 Conceder as permissões necessárias

Substitua o {service-principal-id} pelaid de entidade de serviço copiada na etapa anterior. Substitua o {graph-service-principal-id} pelaid de entidade de serviço copiada na última etapa.

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
{
    "clientId": "{service-principal-id}",
    "consentType": "AllPrincipals",
    "resourceId": "{graph-service-principal-id}",
    "scope": "openid offline_access"
}

4. (Opcional) Adicionar um segredo do cliente

As credenciais permitem que aplicativos confidenciais se identifiquem no serviço de autenticação ao receber tokens. Para garantir, recomendamos usar um certificado (em vez de um segredo do cliente) como uma credencial. Para obter o segredo do cliente, execute a solicitação a seguir. Substitua o {graph-service-principal-id} pelo appId com o appId da primeira etapa.

POST https://graph.microsoft.com/v1.0/applications(appId='appId')/addPassword
{
    "passwordCredential": {
        "displayName": "My app client secret"
    }
}

Na resposta, copie o valor de secretText:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.passwordCredential",
    "displayName": "My app client secret",
    "endDateTime": "2026-05-23T15:16:42",
    "hint": "<Your hint will show up here>",
    "keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
    "secretText": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "startDateTime": "2024-05-23T15:16:42"
}

Fornecer comentários