Partilhar via

Proteja aplicativos Java Spring Boot usando funções e declarações de função

  • Artigo

Este artigo demonstra um aplicativo Web Java Spring Boot que usa a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para autenticação, autorização e aquisição de token. O aplicativo usa o protocolo OpenID Connect para entrar em usuários e restringe o acesso a algumas rotas usando as Funções de Aplicativo do Microsoft Entra ID (funções do aplicativo) para autorização.

As funções do aplicativo, juntamente com os grupos de segurança, são meios populares para implementar a autorização. Usando o RBAC (controle de acesso baseado em função) com funções de aplicativo e declarações de função, você pode aplicar políticas de autorização com segurança com o mínimo de esforço. Outra abordagem é usar grupos de ID do Microsoft Entra e declarações de grupo. Os grupos de ID do Microsoft Entra e as funções de aplicativo não são mutuamente exclusivos. Você pode usá-los ambos para fornecer controle de acesso refinado.

Para assistir a um vídeo que aborda um cenário semelhante, consulte Implementar autorização em seus aplicativos usando funções de aplicativo, grupos de segurança, escopos e funções de diretório.

Para obter mais informações sobre como os protocolos funcionam neste cenário e em outros cenários, consulte Autenticação versus autorização.

O diagrama a seguir mostra a topologia do aplicativo:

Diagrama que mostra a topologia do aplicativo.

O aplicativo usa a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para entrar em um usuário e obter um token de ID do Microsoft Entra ID. O token de ID contém a declaração de funções. O aplicativo inspeciona o valor dessa declaração para determinar quais páginas o usuário está autorizado a acessar.

Este tipo de autorização é implementado usando RBAC. Com o RBAC, um administrador concede permissões a funções, não a usuários individuais ou grupos. O administrador pode, então, atribuir funções a diferentes usuários e grupos para controlar quem tem acesso a determinado conteúdo e funcionalidade.

Este aplicativo de exemplo define as duas funções de aplicativo a seguir:

  • PrivilegedAdmin: Autorizado a aceder às páginas Apenas Administradores e Utilizadores Regulares.
  • RegularUser: Autorizado a aceder à página de Utilizadores Regulares.

Essas funções de aplicativo são definidas no portal do Azure no manifesto de registro do aplicativo. Quando um usuário entra no aplicativo, o Microsoft Entra ID emite uma declaração de funções para cada função concedida individualmente ao usuário na forma de associação de função.

Você pode atribuir usuários e grupos a funções por meio do portal do Azure.

Nota

As declarações de função não estarão presentes para usuários convidados em um locatário se o https://login.microsoftonline.com/common/ ponto de extremidade for usado como autoridade para entrar em usuários. Você precisa entrar um usuário em um ponto de extremidade locatário como https://login.microsoftonline.com/tenantid.

Pré-requisitos

Recomendações

  • Alguma familiaridade com o Quadro da primavera.
  • Alguma familiaridade com o terminal Linux/OSX.
  • jwt.ms para inspecionar seus tokens.
  • Fiddler para monitorizar a sua atividade de rede e resolução de problemas.
  • Siga o Blog do Microsoft Entra ID para ficar atualizado com os últimos desenvolvimentos.

Configurar o exemplo

As seções a seguir mostram como configurar o aplicativo de exemplo.

Clone ou faça download do repositório de exemplo

Para clonar o exemplo, abra uma janela Bash e use o seguinte comando:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/3-Authorization-II/roles

Como alternativa, navegue até o repositório ms-identity-msal-java-samples , faça o download como um arquivo .zip e extraia-o para o disco rígido.

Importante

Para evitar limitações de comprimento de caminho de arquivo no Windows, clone ou extraia o repositório em um diretório perto da raiz do seu disco rígido.

Registrar o aplicativo de exemplo com seu locatário do Microsoft Entra ID

Há um projeto neste exemplo. As seções a seguir mostram como registrar o aplicativo usando o portal do Azure.

Escolha o locatário do Microsoft Entra ID onde você deseja criar seus aplicativos

Para escolher seu locatário, use as seguintes etapas:

  1. Inicie sessão no portal do Azure.

  2. Se sua conta estiver presente em mais de um locatário do Microsoft Entra ID, selecione seu perfil no canto do portal do Azure e selecione Alternar diretório para alterar sua sessão para o locatário desejado do Microsoft Entra ID.

Registrar o aplicativo (java-spring-webapp-roles)

Para registrar o aplicativo, use as seguintes etapas:

  1. Navegue até o portal do Azure e selecione Microsoft Entra ID.

  2. Selecione Registos de Aplicações no painel de navegação e, em seguida, selecione Novo registo.

  3. Na página Registrar um aplicativo que aparece, insira as seguintes informações de registro do aplicativo:

    • Na seção Nome, insira um nome de aplicativo significativo para exibição aos usuários do aplicativo - por exemplo, java-spring-webapp-roles.
    • Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.
    • Na seção Redirecionar URI (opcional), selecione Web na caixa de combinação e digite o seguinte URI de redirecionamento: http://localhost:8080/login/oauth2/code/.

  4. Selecione Registar para criar a aplicação.

  5. Na página de registro do aplicativo, localize e copie o valor da ID do aplicativo (cliente) para usar mais tarde. Você usa esse valor no(s) arquivo(s) de configuração do seu aplicativo.

  6. Na página de registo da aplicação, selecione Certificados & segredos no painel de navegação para abrir a página onde pode gerar segredos e carregar certificados.

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

  8. Digite uma descrição - por exemplo, segredo do aplicativo.

  9. Selecione uma das durações disponíveis: Em 1 ano, Em 2 anos ou Nunca expira.

  10. Selecione Adicionar. O valor gerado é exibido.

  11. Copie e salve o valor gerado para uso em etapas posteriores. Você precisa desse valor para os arquivos de configuração do seu código. Esse valor não é exibido novamente e você não pode recuperá-lo por nenhum outro meio. Portanto, certifique-se de salvá-lo do portal do Azure antes de navegar para qualquer outra tela ou painel.

Definir as funções do aplicativo

Para definir as funções do aplicativo, use as seguintes etapas:

  1. Ainda no mesmo registro de aplicativo, selecione Funções do aplicativo no painel de navegação.

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

    • Em Nome para exibição, insira um nome adequado - por exemplo, PrivilegedAdmin.
    • Em Tipos de membros permitidos, escolha Usuário.
    • Em Valor, insira PrivilegedAdmin.
    • Em Descrição, insira PrivilegedAdmins que podem visualizar a Página de administrador.

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

    • Em Nome para exibição, insira um nome adequado - por exemplo, RegularUser.
    • Em Tipos de membros permitidos, escolha Usuário.
    • Em Valor, insira RegularUser.
    • Em Descrição, insira Usuários Regulares que podem visualizar a Página do Usuário.

  4. Selecione Aplicar para guardar as alterações.

Atribuir usuários a funções de aplicativo

Para adicionar usuários à função de aplicativo definida anteriormente, siga as diretrizes aqui: Atribuir usuários e grupos a funções.

Configure o aplicativo (java-spring-webapp-roles) para usar o registro do aplicativo

Use as seguintes etapas para configurar o aplicativo:

Nota

Nas etapas a seguir, ClientID é o mesmo que Application ID ou AppId.

  1. Abra o projeto no seu IDE.

  2. Abra o arquivo src\main\resources\application.yml .

  3. Localize o espaço reservado Enter_Your_Tenant_ID_Here e substitua o valor existente pelo ID de locatário do Microsoft Entra.

  4. Localize o espaço reservado Enter_Your_Client_ID_Here e substitua o valor existente pela ID do aplicativo ou clientId do java-spring-webapp-roles aplicativo copiado do portal do Azure.

  5. Localize o espaço reservado Enter_Your_Client_Secret_Here e substitua o valor existente pelo valor que você salvou durante a criação do java-spring-webapp-roles copiado do portal do Azure.

  6. Abra o arquivo src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootapplication/Sample.Controller.java .

  7. Encontre as referências às funções e RegularUser aplicativo PrivilegedAdmin neste arquivo. Se necessário, altere-os para refletir os nomes de função do aplicativo escolhidos nas etapas anteriores.

Executar o exemplo

As seções a seguir mostram como implantar o exemplo em Aplicativos de Contêiner do Azure.

Pré-requisitos

Preparar o projeto primavera

Use as seguintes etapas para preparar o projeto:

  1. Use o seguinte comando Maven para criar o projeto:

    mvn clean verify

  2. Execute o projeto de exemplo localmente usando o seguinte comando:

    mvn spring-boot:run

Configurar

Para entrar no Azure a partir da CLI, execute o seguinte comando e siga os prompts para concluir o processo de autenticação.

az login

Para garantir que você esteja executando a versão mais recente da CLI, execute o comando upgrade.

az upgrade

Em seguida, instale ou atualize a extensão Aplicativos de Contêiner do Azure para a CLI.

Se você receber erros sobre parâmetros ausentes ao executar az containerapp comandos na CLI do Azure, certifique-se de ter a versão mais recente da extensão Aplicativos de Contêiner do Azure instalada.

az extension add --name containerapp --upgrade

Nota

A partir de maio de 2024, as extensões da CLI do Azure não habilitam mais recursos de visualização por padrão. Para acessar os recursos de visualização do Container Apps, instale a extensão Container Apps com --allow-preview trueo .

az extension add --name containerapp --upgrade --allow-preview true

Agora que a extensão ou módulo atual está instalado, registre os Microsoft.App namespaces e Microsoft.OperationalInsights .

Nota

Os recursos dos Aplicativos de Contêiner do Azure migraram do Microsoft.Web namespace para o Microsoft.App namespace. Consulte Migração de namespace de Microsoft.Web para Microsoft.App em março de 2022 para obter mais detalhes.

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Criar o ambiente de Aplicativos de Contêiner do Azure

Agora que a configuração da CLI do Azure está concluída, você pode definir as variáveis de ambiente usadas ao longo deste artigo.

Defina as seguintes variáveis em seu shell bash.

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

Crie um grupo de recursos.

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

Crie um ambiente com um espaço de trabalho do Log Analytics gerado automaticamente.

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

Mostrar o domínio padrão do ambiente do aplicativo de contêiner. Anote este domínio para usar em seções posteriores.

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

Preparar o aplicativo para implantação

Quando você implanta seu aplicativo nos Aplicativos de Contêiner do Azure, sua URL de redirecionamento muda para a URL de redirecionamento da instância do aplicativo implantado nos Aplicativos de Contêiner do Azure. Use as seguintes etapas para alterar essas configurações no arquivo application.yml :

  1. Navegue até o arquivo src\main\resources\application.yml do seu aplicativo e altere o valor de para o nome de domínio do post-logout-redirect-uri aplicativo implantado, conforme mostrado no exemplo a seguir. Certifique-se de substituir <API_NAME> e <default-domain-of-container-app-environment> com seus valores reais. Por exemplo, com o domínio padrão para seu ambiente de Aplicativo de Contêiner do Azure da etapa anterior e ms-identity-api para o nome do seu aplicativo, você usaria https://ms-identity-api.<default-domain> para o post-logout-redirect-uri valor.

    post-logout-redirect-uri: https://<API_NAME>.<default-domain-of-container-app-environment>

  2. Depois de salvar esse arquivo, use o seguinte comando para reconstruir seu aplicativo:

    mvn clean package

Importante

O arquivo application.yml do aplicativo atualmente contém o valor do segredo do cliente no client-secret parâmetro. Não é uma boa prática manter esse valor neste arquivo. Você também pode estar correndo um risco se confirmar o arquivo em um repositório Git. Para obter a abordagem recomendada, consulte Gerenciar segredos em Aplicativos de Contêiner do Azure.

Atualizar o registo da aplicação Microsoft Entra ID

Como o URI de redirecionamento é alterado para seu aplicativo implantado em Aplicativos de Contêiner do Azure, você também precisa alterar o URI de redirecionamento no registro do aplicativo Microsoft Entra ID. Use as seguintes etapas para fazer essa alteração:

  1. Navegue até a página Registros de aplicativos da plataforma de identidade da Microsoft para desenvolvedores.

  2. Use a caixa de pesquisa para pesquisar o registro do seu aplicativo - por exemplo, java-servlet-webapp-authentication.

  3. Abra o registro do aplicativo selecionando seu nome.

  4. Selecione Autenticação a partir do menu.

  5. Na seção URIs de redirecionamento da Web - , selecione Adicionar URI.

  6. Preencha o URI do seu aplicativo, anexando /login/oauth2/code/ - por exemplo, https://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/.

  7. Selecione Guardar.

Implementar a aplicação

Implante o pacote JAR nos Aplicativos de Contêiner do Azure.

Nota

Se necessário, você pode especificar a versão do JDK nas variáveis de ambiente de construção Java. Para obter mais informações, consulte Criar variáveis de ambiente para Java em Aplicativos de Contêiner do Azure.

Agora você pode implantar seu arquivo WAR com o az containerapp up comando CLI.

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Nota

A versão padrão do JDK é 17. Se você precisar alterar a versão do JDK para compatibilidade com seu aplicativo, poderá usar o --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> argumento para ajustar o número da versão.

Para obter mais variáveis de ambiente de compilação, consulte Criar variáveis de ambiente para Java em Aplicativos de Contêiner do Azure.

Validar a aplicação

Neste exemplo, o containerapp up comando inclui o --query properties.configuration.ingress.fqdn argumento, que retorna o nome de domínio totalmente qualificado (FQDN), também conhecido como URL do aplicativo. Use as seguintes etapas para verificar os logs do aplicativo para investigar qualquer problema de implantação:

  1. Acesse a URL do aplicativo de saída na página Saídas da seção Implantação .

  2. No painel de navegação da página Visão Geral da instância dos Aplicativos de Contêiner do Azure, selecione Logs para verificar os logs do aplicativo.

Explorar o exemplo

Use as seguintes etapas para explorar o exemplo:

  1. Observe o status de entrada ou saída exibido no centro da tela.
  2. Selecione o botão sensível ao contexto no canto. Este botão lê Iniciar sessão quando executa a aplicação pela primeira vez. Como alternativa, selecione detalhes do token, somente administradores ou usuários comuns. Como essas páginas são protegidas e exigem autenticação, você é automaticamente redirecionado para a página de login.
  3. Na página seguinte, siga as instruções e entre com uma conta no locatário do Microsoft Entra ID.
  4. Na tela de consentimento, observe os escopos que estão sendo solicitados.
  5. Após a conclusão bem-sucedida do fluxo de entrada, você deve ser redirecionado para a página inicial - que mostra o status de entrada - ou uma das outras páginas, dependendo de qual botão acionou seu fluxo de login.
  6. Observe que o botão sensível ao contexto agora diz Sair e exibe seu nome de usuário.
  7. Se você estiver na página inicial, selecione Detalhes do token de ID para ver algumas das declarações decodificadas do token de ID, incluindo funções.
  8. Selecione Somente administradores para exibir o /admin_onlyarquivo . Somente os usuários com função PrivilegedAdmin de aplicativo podem visualizar esta página. Caso contrário, uma mensagem de falha de autorização será exibida.
  9. Selecione Usuários regulares para visualizar a /regular_user página. Somente usuários com função RegularUser de aplicativo ou PrivilegedAdmin podem exibir esta página. Caso contrário, uma mensagem de falha de autorização será exibida.
  10. Use o botão no canto para sair. A página de status reflete o novo estado.

Sobre o código

Este exemplo demonstra como usar a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para entrar usuários em seu locatário do Microsoft Entra ID. O exemplo também faz uso dos iniciadores de inicialização do Spring Oauth2 Client e do Spring Web. O exemplo usa declarações do token de ID obtido do Microsoft Entra ID para exibir os detalhes do usuário conectado e para restringir o acesso a algumas páginas usando a declaração de funções para autorização.

Conteúdos

A tabela a seguir mostra o conteúdo da pasta de projeto de exemplo:

Ficheiro/pasta Description
pom.xml Dependências de aplicativos.
src/main/recursos/modelos/ Modelos Thymeleaf para UI.
src/principal/recursos/application.yml Configuração da biblioteca de inicialização do aplicativo e do Microsoft Entra ID.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Este diretório contém o ponto de entrada principal do aplicativo, controlador e classes de configuração.
.../MsIdentitySpringBootWebappApplication.java Classe principal.
.../SampleController.java Controlador com mapeamentos de pontos finais.
.../SecurityConfig.java Configuração de segurança - por exemplo, quais rotas exigem autenticação.
.../Utilities.java Classe de utilitário - por exemplo, declarações de token de ID de filtro.
CHANGELOG.md Lista de alterações à amostra.
CONTRIBUTING.md Orientações para contribuir para a amostra.
LICENÇA» A licença para a amostra.

Declarações de token de ID

Para extrair detalhes do token, o aplicativo usa o AuthenticationPrincipal objeto e OidcUser o objeto do Spring Security em um mapeamento de solicitação, conforme mostrado no exemplo a seguir. Consulte o Controlador de exemplo para obter os detalhes completos de como este aplicativo usa as declarações de token de ID.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Processar uma declaração de funções no token de ID

A declaração de funções do token inclui os nomes das funções às quais o usuário conectado está atribuído, conforme mostrado no exemplo a seguir:

{
  ...
  "roles": [
    "PrivilegedAdmin",
    "RegularUser",]
  ...
}

Uma maneira comum de acessar os nomes de função está documentada na seção de declarações de token de ID.

O Microsoft Entra ID Boot Starter v3.3 e superior também analisa a declaração de funções automaticamente e adiciona cada função à do usuário conectado, prefixando cada uma com a cadeia de Authoritiescaracteres APPROLE_. Essa configuração permite que os desenvolvedores usem funções de aplicativo com anotações de condição do Spring PrePost usando o hasAuthority método. Por exemplo, você pode encontrar as seguintes @PreAuthorize condições demonstradas em SampleController.java:

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('APPROLE_PrivilegedAdmin')")
public String adminOnly(Model model) {
    // restrict to users who have PrivilegedAdmin app role only
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('APPROLE_PrivilegedAdmin','APPROLE_RegularUser')")
public String regularUser(Model model) {
    // restrict to users who have any of RegularUser or PrivilegedAdmin app roles
}

O código a seguir obtém uma lista completa de autoridades para um determinado usuário:

@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
   Collection<? extends GrantedAuthority> authorities = principal.getAuthorities();
}

Para entrar, o aplicativo faz uma solicitação ao ponto de extremidade de entrada do Microsoft Entra ID configurado automaticamente pela biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java, conforme mostrado no exemplo a seguir:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Para sair, o aplicativo faz uma solicitação POST para o logout ponto de extremidade, conforme mostrado no exemplo a seguir:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Elementos da interface do usuário dependentes de autenticação

O aplicativo tem alguma lógica simples nas páginas de modelo da interface do usuário para determinar o conteúdo a ser exibido com base na autenticação do usuário, conforme mostrado no exemplo a seguir usando as tags Spring Security Thymeleaf:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Proteja rotas com AADWebSecurityConfigurerAdapter

Por padrão, o aplicativo protege as páginas Detalhes do token de ID, Somente administradores e Usuários regulares para que apenas usuários conectados possam acessá-las. O aplicativo configura essas rotas a partir da app.protect.authenticated propriedade do arquivo application.yml . Para configurar os requisitos específicos do seu aplicativo, você pode estender AADWebSecurityConfigurationAdapter em uma de suas classes. Para obter um exemplo, consulte a classe SecurityConfig deste aplicativo, mostrada no código a seguir:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /admin_only, /regular_user)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Mais informações

Para obter mais informações sobre como os protocolos OAuth 2.0 funcionam neste cenário e em outros cenários, consulte Cenários de autenticação para o Microsoft Entra ID.