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

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 ao grupo Entra ID.

Neste tutorial, irá aprender a:

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

Há uma função chamada GetRoles na API do aplicativo. Esta função usa o token de acesso do usuário para consultar o ID do Entra 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. Vá para o seguinte local para criar um novo repositório.

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

2. Nomeie seu repositório como my-custom-roles-app.

3. Selecione Criar repositório a partir de modelo.

Implantar o 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 Aplicações Web Estáticas.

5. Selecione Criar.

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

   Definição	Value	Notas
   Subscrição	Selecione a subscrição do Azure.
   Grupo de recursos	Crie um novo grupo chamado my-custom-roles-app-group.
   Nome	my-custom-roles-app
   Tipo de plano	Standard	Personalizar a autenticação e atribuir funções usando uma função requer o plano Padrão .
   Região para API	Selecione a região mais próxima de si.

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

   Definição	Value
   Source	Selecione GitHub.
   Organization	Selecione a organização onde você gerou o repositório.
   Repositório	Selecione my-custom-roles-app.
   Filial	Selecione principal.

8. Na seção Build Details, adicione os detalhes de configuração para este aplicativo.

   Definição	Value	Notas
   Predefinições de compilação	Selecione Personalizado.
   Localização da aplicação	Digite /frontend.	Esta pasta contém o aplicativo front-end.
   Localização da API	/api	Pasta no repositório que contém as funções da API.
   Local de saída	Deixe em branco.	Este aplicativo não tem saída de compilação.

9. Selecione Rever + criar.

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

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

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

Criar um aplicativo Microsoft Entra

1. No portal do Azure, procure e vá para Microsoft Entra ID.

2. No menu Gerenciar, selecione Registros de aplicativos.

3. Selecione Novo registro para abrir a janela Registrar um aplicativo . Introduza os seguintes valores:

   Definição	Value	Notas
   Nome	Digite MyStaticWebApp.
   Tipos de conta suportados	Selecione Contas somente neste diretório organizacional.
   Redirecionar URL	Selecione Web e insira a URL de retorno de chamada de autenticação do Microsoft Entra do seu aplicativo Web estático. Substitua <YOUR_SITE_URL> pelo <YOUR_SITE_URL>/.auth/login/aad/callback URL do seu aplicativo Web estático.	Este URL é o que você copiou para um editor de texto em uma etapa anterior.

   

4. Selecione Registar.

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

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

Ativar 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 tempo de execução dos Static Web Apps requer essa configuração para autenticar seus usuários.

3. Selecione Guardar.

Criar um segredo do cliente

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

2. Na seção Segredos do cliente, selecione Novo segredo do cliente.

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

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

   Nota

   Você deve girar o segredo antes da data de expiração, gerando um novo segredo e atualizando seu aplicativo com seu valor.

5. Selecione Adicionar.

6. Copie o valor do segredo do cliente criado para um editor de texto.

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

   

Configurar a autenticação do Entra ID

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

   Vá para o arquivo de configuração do aplicativo em frontend/staticwebapp.config.json. Este ficheiro contém a seguinte secção:

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

   Esta configuração é composta pelas seguintes definições:

   Propriedades	Description
   rolesSource	A URL onde o processo de login 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 login.
   openIdIssuer	A rota de login do Microsoft Entra, anexada com sua ID de locatário.
   clientIdSettingName	A sua ID de cliente Microsoft Entra.
   clientSecretSettingName	Seu valor secreto do cliente Microsoft Entra.
   loginParameters	Para obter um token de acesso para o Microsoft Graph, o loginParameters campo deve ser configurado com resource=https://graph.microsoft.com.

2. Selecione Editar para atualizar o arquivo.

3. Atualize o valor openIdIssuer substituindo <YOUR_ENTRA_TENANT_ID> pela ID do https://login.microsoftonline.com/<YOUR_ENTRA_TENANT_ID> diretório (locatário) da sua ID do Microsoft Entra.

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

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

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

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

7. Selecione Configuração na barra de menus.

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

   Nome	Valor
   ENTRA_CLIENT_ID	O seu ID de aplicação (cliente) Entra ID.
   ENTRA_CLIENT_SECRET	Seu valor secreto do cliente do aplicativo Entra.

9. Selecione Guardar.

Criar funções

1. Abra o registro do aplicativo Entra ID no portal do Azure.

2. Em Gerir, selecione Funções da aplicação.

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

   Definição	valor
   Display name	Digite admin.
   Tipos de membros permitidos	Selecione Usuários/Grupos.
   Value	Digite admin.
   Description	Digite Administrador.

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

5. Selecione Aplicar.

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

7. Copie os valores de ID para cada função e reserve-os 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 GitHub, vá para a função GetRoles localizada em api/GetRoles/index.js.

   Na parte superior, há um roleGroupMappings objeto que mapeia funções de usuário personalizadas para grupos do Microsoft Entra.

2. Selecione Editar.

3. Atualize o objeto com IDs de grupo do locatário do Microsoft Entra.

   Por exemplo, se você tiver grupos com IDs 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 e b6059db5-9cef-4b27-9434-bb793aa31805, atualizaria 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 com o ID do Microsoft Entra. A função usa o token de acesso do usuário para consultar sua associação ao grupo Entra do Microsoft Graph. Se o usuário for membro de quaisquer grupos definidos no roleGroupMappings objeto, as funções personalizadas correspondentes serão retornadas.

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

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

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

   Fazer essas alterações inicia uma compilação para atualizar o aplicativo Web estático.

6. Quando a implantação estiver concluída, você poderá verificar suas 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 atribuídas a você com base na associação ao grupo Entra ID da sua identidade.

   Dependendo dessas funções, você tem permissão ou proibição de acessar algumas das rotas no aplicativo.

Clean up resources (Limpar recursos)

Limpe os recursos implantados excluindo o grupo de recursos.

1. No portal do Azure, selecione Grupo de recursos no menu à esquerda.

2. Introduza o nome do grupo de recursos no campo Filtrar por nome.

3. Selecione o nome do grupo de recursos usado neste tutorial.

4. Selecione Eliminar grupo de recursos no menu superior.

Próximos passos