Tutorial: Atribuir funções personalizadas com uma função e o Microsoft Graph

Este artigo demonstra como usar uma função para consultar o Microsoft Graph e atribuir funções personalizadas a um usuário com base em sua associação de grupo do Active Directory.

Neste tutorial, você aprenderá a:

• Implantar um aplicativo Web estático.
• Crie um registro de aplicativo do Microsoft Entra.
• Configure a autenticação personalizada com o Microsoft Entra ID.
• Configurar uma função sem servidor que consulta a associação de grupo do Active Directory do usuário e retorna uma lista de funções personalizadas.

Há uma função chamada GetRoles na API do aplicativo. Essa função usa o token de acesso do usuário para consultar o Active Directory do Microsoft Graph. Se o usuário for membro de qualquer grupo definido no aplicativo, as funções personalizadas correspondentes serão mapeadas para o usuário.

Pré-requisitos

Criar um repositório GitHub

1. Gere um repositório com base no modelo de função de funções. Navegue até a seguinte localização para criar um repositório.

   https://github.com/staticwebdev/roles-function/generate

2. Dê ao repositório o nome my-custom-roles-app.

3. Selecione Criar repositório com base no modelo.

Implantar um aplicativo Web estático no Azure

1. Em uma nova janela do navegador, abra o portal do Azure.

2. No canto superior esquerdo, selecione Criar um recurso.

3. Na caixa de pesquisa, digite aplicativos Web estáticos.

4. Selecione Aplicativos Web Estáticos.

5. Selecione Criar.

6. Configure seu aplicativo Web estático com as seguintes informações:

   Configuração	Valor	Observações
   Subscription	Selecione sua assinatura do Azure.
   Resource group	Crie um novo grupo chamado my-custom-roles-app-group.
   Nome	my-custom-roles-app
   Tipo de plano	Standard	A personalização da autenticação e a atribuição de funções usando uma função exigem o plano Standard.
   Região para a API	Selecione a região mais próxima de você.

7. Na seção Detalhes da implantação:

   Configuração	Valor
   Fonte	Selecione GitHub.
   Organização	Selecione a organização na qual você gerou o repositório.
   Repositório	Selecione my-custom-roles-app.
   Branch	Selecione main.

8. Na seção Detalhes do Build, adicione os detalhes da configuração para esse aplicativo.

   Configuração	Valor	Observações
   Predefinições de build	selecione Personalizado.
   Localização do aplicativo	Insira /frontend.	Essa pasta contém o aplicativo front-end.
   Localização da API	/api	Pasta no repositório que contém as funções de API.
   local de saída	Deixe em branco.	Esse aplicativo não tem nenhuma saída de build.

9. Selecione Examinar + criar.

10. Selecione Criar para iniciar a primeira implantação.

11. Depois que o processo for concluído, selecione Ir para o recurso para abrir o seu novo aplicativo Web estático.

12. Na seção de visão geral, localize a URL do aplicativo. Copie esse valor em um editor de texto para usar nas próximas etapas para configurar a autenticação do Active Directory.

Criar um aplicativo do Microsoft Entra

1. No portal do Azure, pesquise e acesse Microsoft Entra ID.

2. No menu Gerenciar, selecione Registros de aplicativo.

3. Selecione Novo registro para abrir a janela Registrar um aplicativo. Insira os valores a seguir:

   Configuração	Valor	Observações
   Nome	Insira MyStaticWebApp.
   Tipos de conta com suporte	Escolha Somente contas neste diretório organizacional.
   URI de redirecionamento	Selecione Web e insira o retorno de chamada de autenticação do Microsoft Entra URL do seu aplicativo Web estático. Substitua <YOUR_SITE_URL> em <YOUR_SITE_URL>/.auth/login/aad/callback pela URL do aplicativo Web estático.	Essa URL é o que você copiou para um editor de texto em uma etapa anterior.

   

4. Selecione Registrar.

5. Depois que o registro do aplicativo for criado, copie a ID do aplicativo (cliente) e a ID do Directory (locatário) na seção Essentials para um editor de texto.

   Você precisa desses valores para configurar a autenticação do Active Directory em seu aplicativo Web estático.

Habilitar tokens de ID

1. Nas configurações de registro do aplicativo, selecione Autenticação em Gerenciar.

2. Na seção Concessão implícita e fluxos híbridos, selecione Tokens de ID (usados para fluxos implícitos e híbridos).

   O runtime dos Aplicativos Web Estáticos requer essa configuração para autenticar seus usuários.

3. Clique em Salvar.

Criar um segredo do cliente

1. Nas configurações de registro do aplicativo, selecione Certificados e segredos em Gerenciar.

2. Na seção Segredos do Cliente, escolha Novo Segredo do Cliente.

3. Para o campo Descrição, insira MyStaticWebApp.

4. Para o campo Expira, deixe o valor padrão de 6 meses.

   Observação

   Você deve girar o segredo antes da data de validade gerando outra segredo e atualizando seu aplicativo com seu valor.

5. Selecione Adicionar.

6. Copie o Valor do segredo do cliente que você criou para um editor de texto.

   Você precisa desse valor para configurar a autenticação do Active Directory em seu aplicativo Web estático.

   

Configurar a autenticação do Active Directory

1. Em um navegador, abra o repositório GitHub que contém o aplicativo Web estático implantado.

   Vá para o arquivo de configuração do aplicativo em frontend/staticwebapp.config.json. Este arquivo inclui a seção a seguir:

   "auth": {
     "rolesSource": "/api/GetRoles",
     "identityProviders": {
       "azureActiveDirectory": {
         "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
         "registration": {
           "openIdIssuer": "https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID>",
           "clientIdSettingName": "AAD_CLIENT_ID",
           "clientSecretSettingName": "AAD_CLIENT_SECRET"
         },
         "login": {
           "loginParameters": [
             "resource=https://graph.microsoft.com"
           ]
         }
       }
     }
   },
   

   Esta configuração é composta pelo seguinte:

   Propriedades	Descrição
   rolesSource	A URL em que o processo de logon obtém uma lista de funções disponíveis. Para o aplicativo de exemplo, a URL é /api/GetRoles.
   userDetailsClaim	A URL do esquema usado para validar a solicitação de logon.
   openIdIssuer	A rota de logon do Microsoft Entra, acrescentada à sua ID de locatário.
   clientIdSettingName	Sua ID do cliente do Microsoft Entra.
   clientSecretSettingName	O valor do segredo do cliente do Microsoft Entra.
   loginParameters	Para obter um token de acesso para o Microsoft Graph, o campo loginParameters deve ser configurado com resource=https://graph.microsoft.com.

2. Selecione Editar para atualizar o arquivo.

3. Atualizações do valor openIdIssuer de https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID> substituindo <YOUR_AAD_TENANT_ID> pela ID do diretório (locatário) do seu Microsoft Entra ID.

4. Selecione Confirmar alterações....

5. Insira um mensagem de confirmação e selecione Confirmar alterações.

   A confirmação dessas alterações inicia uma execução do GitHub Actions para atualizar o aplicativo Web estático.

6. Vá para um recurso de aplicativo Web estático no portal do Azure.

7. Na barra de menus, selecione Configuração.

8. Na seção Configurações do aplicativo, adicione as seguintes configurações:

   Nome	Valor
   AAD_CLIENT_ID	A ID (cliente) do aplicativo do Active Directory.
   AAD_CLIENT_SECRET	O valor de segredo do cliente do aplicativo do Active Directory.

9. Selecione Salvar.

Criar Funções

1. Abra o registro de aplicativo do Active Directory no portal do Azure.

2. Em Gerenciar, selecione Funções do aplicativo.

3. Selecione Criar função de aplicativo e insira os seguintes valores:

   Configuração	Valor
   Nome de exibição	Insira administrador.
   Tipos de membro permitidos	Selecione Usuários/Grupos.
   Valor	Insira administrador.
   Descrição	Insira Administrador.

4. Marque a caixa de seleção Deseja habilitar essa função de aplicativo?

5. Escolha Aplicar.

6. Agora, repita o mesmo processo para uma função chamada leitor.

7. Copie os valores de ID para cada função e deixe-os de lado em um editor de texto.

Verificar funções personalizadas

O aplicativo de exemplo contém uma função de API (api/GetRoles/index.js) que consulta o Microsoft Graph para determinar se um usuário está em um grupo predefinido.

Com base nas associações de grupo do usuário, a função atribui funções personalizadas ao usuário. O aplicativo é configurado para restringir determinadas rotas com base nessas funções personalizadas.

1. No repositório do GitHub, vá para a função GetRoles localizada em api/GetRoles/index.js.

   Perto do topo, existe um objeto roleGroupMappings que mapeia as funções de usuário personalizadas para os grupos do Microsoft Entra.

2. Selecione Editar.

3. Atualizações do objeto com IDs de grupo do seu locatário do Microsoft Entra ID.

   Por exemplo, se você tiver grupos com as IDs 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 e b6059db5-9cef-4b27-9434-bb793aa31805, atualizará o objeto para:

   const roleGroupMappings = {
     'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
     'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
   };
   

   A função GetRoles é chamada sempre que um usuário é autenticado com êxito no Microsoft Entra ID. A função usa o token de acesso do usuário para consultar sua associação de grupo do Active Directory do Microsoft Graph. Se o usuário for membro de qualquer grupo definido no objeto roleGroupMappings, as funções personalizadas correspondentes serão retornadas.

   No exemplo acima, se um usuário for um membro do grupo do Active Directory com a ID b6059db5-9cef-4b27-9434-bb793aa31805, ele receberá a função reader.

4. Selecione Confirmar alterações....

5. Adicione uma mensagem de confirmação e selecione Confirmar alterações.

   Fazer essas alterações inicia um build para atualizar o aplicativo Web estático.

6. Quando a implantação for concluída, você poderá verificar as alterações navegando até a URL do aplicativo.

7. Entre no seu aplicativo Web estático usando o Microsoft Entra ID.

8. Quando você estiver conectado, o aplicativo de exemplo exibirá a lista de funções que você atribuiu com base na associação de grupo do Active Directory de sua identidade.

   Dependendo dessas funções, você será permitido ou impedido de acessar algumas das rotas no aplicativo.

Limpar os recursos

Limpe os recursos que você implantou excluindo o grupo de recursos.

1. No portal do Azure, escolha Grupos de recursos do menu à esquerda.

2. No campo Filtrar por nome, insira o nome do grupo de recursos.

3. Selecione o nome do grupo de recursos que você usou neste tutorial.

4. Escolha Excluir grupo de recursos no menu superior.

Próximas etapas