Configurar a declaração de função

  • Artigo

Você pode personalizar a declaração de função no token de acesso recebido após a autorização de um aplicativo. Use esse recurso se seu aplicativo espera funções personalizadas no token retornado pelo Azure AD. É possível criar quantas funções forem necessárias.

Pré-requisitos

Observação

Este artigo explica como criar, atualizar ou excluir funções de aplicativo na entidade de serviço por meio de APIs. Para usar a nova interface do usuário para Funções de Aplicativo, confira Adicionar funções de aplicativo ao seu aplicativo e recebê-las no token.

Localizar o aplicativo empresarial

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Use as seguintes etapas para localizar o aplicativo empresarial:

  1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
  2. Navegue até Identidade>Aplicativos>Aplicativos Empresariais>Todos os aplicativos.
  3. Insira o nome do aplicativo existente na caixa de pesquisa e, em seguida, selecione o aplicativo nos resultados da pesquisa.
  4. Depois que o aplicativo for selecionado, copie a ID do objeto no painel de visão geral.

Adicionar funções

Use o Explorador do Microsoft Graph para adicionar funções a um aplicativo empresarial.

  1. Abra o Explorador do Microsoft Graph em outra janela e entre usando as credenciais de administrador global para o seu locatário.

    Observação

    As funções de Administrador de Aplicativos de Nuvem e Administrador de Aplicativos não irão funcionar nesse cenário. Use o Administrador de Funções com Privilégios.

  2. Selecione modificar permissões, selecione Consentimento para as permissões Application.ReadWrite.All e Directory.ReadWrite.All na lista.

  3. Substitua <objectID> na solicitação a seguir pela ID do objeto que foi registrada anteriormente e, em seguida, execute a consulta:

    https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>

  4. Aplicativos empresariais também são chamados de entidades de serviço. Registre a propriedade appRoles do objeto da entidade de serviço que foi retornado. O exemplo a seguir mostra a propriedade appRoles típica:

    {
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    }
  ]
}

  5. No Explorador do Microsoft Graph, altere o método de GET para PATCH.

  6. Copie a propriedade appRoles que foi registrada anteriormente no painel Corpo da solicitação do Explorador do Graph, adicione a nova definição de função e selecione Executar Consulta para executar a operação de patch. Uma mensagem confirma a criação da função. O exemplo a seguir mostra a adição de uma função Administrador:

    {
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    },
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "Administrators Only",
      "displayName": "Admin",
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "isEnabled": true,
      "origin": "ServicePrincipal",
      "value": "Administrator"
    }
  ]
}

    Você deve incluir o objeto de função msiam_access além de quaisquer novas funções no corpo da solicitação. A não inclusão de quaisquer funções existentes no corpo da solicitação as remove do objeto appRoles. Além disso, você pode adicionar quantas regras quiser de acordo com a necessidade da sua organização. O valor dessas funções é enviado como um valor da declaração na resposta SAML. Para gerar os valores de GUID para a ID de novas funções, use as ferramentas da Web, como o Guid Online/Gerador UUID. A propriedade appRoles na resposta inclui o que estava no corpo da solicitação da consulta.

Editar Atributos

Atualize os atributos para definir a declaração de função incluída no token.

  1. Localize o aplicativo no Centro de administração do Microsoft Entra e selecione Logon único no menu à esquerda.
  2. Na seção Atributos e Declarações, selecione Editar.
  3. Selecione Adicionar nova declaração.
  4. Na caixa Nome, digite o nome do atributo. Este exemplo usa Nome da Função como o nome da declaração.
  5. Deixe a caixa Namespace em branco.
  6. Na lista Atributo de origem, selecione user.assignedroles.
  7. Selecione Salvar. O novo atributo Nome da Função agora deve aparecer na seção Atributos e Declarações. A declaração agora deve ser incluída no token de acesso ao entrar no aplicativo.

Atribuir funções

Após a atualização da entidade de serviço com mais funções, será possível atribuir usuários às respectivas funções.

  1. Localize o aplicativo ao qual a função foi adicionada no Centro de administração do Microsoft Entra.
  2. Selecione Usuários e grupos no menu à esquerda e, em seguida, selecione o usuário ao qual você deseja atribuir a nova função.
  3. Selecione Editar atribuição na parte superior do painel para alterar a função.
  4. Selecione Nenhum Selecionado, selecione a função na lista e selecione Selecionar.
  5. Selecione Atribuir para atribuir a função ao usuário.

Atualizar funções

Para atualizar uma função existente, execute as seguintes etapas:

  1. Abra o Microsoft Graph Explorer.

  2. Faça login no site do Explorador do Graph como Administrador de Funções com Privilégios.

  3. Usando a ID do objeto para o aplicativo no painel de visão geral, substitua <objectID> na seguinte solicitação por ela e execute a consulta:

    https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>

  4. Registre a propriedade appRoles do objeto da entidade de serviço que foi retornado.

  5. No Explorador do Microsoft Graph, altere o método de GET para PATCH.

  6. Copie a propriedade appRoles que foi registrada anteriormente no painel Corpo da solicitação do Explorador do Graph, adicione a definição de atualização de função e selecione Executar Consulta para executar a operação de patch.

Excluir funções

Para excluir uma função existente, execute as seguintes etapas:

  1. Abra o Microsoft Graph Explorer.

  2. Faça login no site do Explorador do Graph como Administrador de Funções com Privilégios.

  3. Usando a ID do objeto para o aplicativo no painel de visão geral no portal do Azure, substitua <objectID> na seguinte solicitação por ela e execute a consulta:

    https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>

  4. Registre a propriedade appRoles do objeto da entidade de serviço que foi retornado.

  5. No Explorador do Microsoft Graph, altere o método de GET para PATCH.

  6. Copie a propriedade appRoles que foi registrada anteriormente no painel Corpo da solicitação do Explorador do Graph, defina o valor IsEnabled como false para a função que você deseja excluir e selecione Executar Consulta para executar a operação de patch. Uma função deve ser desabilitada antes de ser excluída.

  7. Depois que a função é desabilitada, exclua esse bloco de função na seção appRoles. Mantenha o método como PATCH e selecione Executar Consulta novamente.

Próximas etapas