Proteja aplicativos Java WebSphere usando funções de aplicativo e declarações de função

Este artigo demonstra uma aplicação Java WebSphere que utiliza OpenID Connect para iniciar sessão dos utilizadores e Funções de Aplicação do Microsoft Entra ID (funções da aplicação) para autorização.

Este aplicativo implementa o controle de acesso baseado em função (RBAC) usando as funções de aplicativo e o recurso de declarações de função do Microsoft Entra ID. Outra abordagem é utilizar grupos do Microsoft Entra ID e alegações de grupo. Os grupos do Microsoft Entra ID e as funções da aplicação não são mutuamente exclusivas. Você pode usá-los ambos para fornecer controle de acesso refinado.

Você também pode usar o RBAC com funções de aplicativo e declarações de função para aplicar políticas de autorização com segurança.

Para ver um vídeo que abrange este cenário e este exemplo, veja Implementar a autorização nas suas aplicações com funções da aplicação, grupos de segurança, âmbitos e funções do diretório.

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

Esta aplicação utiliza MSAL para Java (MSAL4J) para iniciar sessão de um utilizador e obter um ID token do Microsoft Entra ID.

Este exemplo usa primeiro o MSAL para Java (MSAL4J) para entrar no usuário. Na página inicial, ele exibe uma opção para o usuário visualizar as declarações em seus tokens de ID. Este aplicativo também permite que os usuários visualizem uma página de administração privilegiada ou uma página de usuário regular, dependendo da função do aplicativo à qual foram atribuídos. A ideia é fornecer um exemplo de como, dentro de um aplicativo, o acesso a determinadas funcionalidades ou páginas é restrito a subconjuntos de usuários, dependendo da função a que pertencem.

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.

Esta aplicação de exemplo define as duas Funções da Aplicação seguintes:

: Autorizado a aceder às páginas Só para administradores e Utilizadores regulares.
: Autorizado a aceder à página Utilizadores Regulares.

Estas funções da aplicação são definidas no portal do Azure no manifesto de registo da aplicação. Quando um utilizador inicia sessão na aplicação, o Microsoft Entra ID emite uma declaração de função para cada função concedida individualmente ao utilizador sob a forma de pertença à função.

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

Nota

As claims de função não estão presentes para utilizadores convidados num tenant se o endpoint for utilizado como autoridade para iniciar sessão dos utilizadores. Tem de iniciar sessão de um utilizador num endpoint associado a um inquilino, como .

Pré-requisitos

JDK versão 8 ou posterior
Maven 3
Um inquilino do Microsoft Entra ID. Para obter mais informações, consulte Como obter um inquilino do Microsoft Entra ID.
Uma conta de utilizador no seu próprio inquilino do Microsoft Entra ID, caso pretenda trabalhar apenas com contas no diretório da sua organização — ou seja, no modo de inquilino único. Se ainda não criou uma conta de utilizador no seu tenant, deve fazê-lo antes de prosseguir. Para obter mais informações, consulte Como criar, convidar e eliminar utilizadores.

WebSphere
Visual Studio Code
Ferramentas do Azure para Visual Studio Code

Recomendações

Alguma familiaridade com os Servlets Java / Jakarta.
Alguma familiaridade com o terminal Linux/OSX.
jwt.ms para inspecionar os seus tokens.
Fiddler para monitorizar a atividade da sua rede e diagnosticar e resolver problemas.
Siga o Blog do Microsoft Entra para ficar up-toa par dos ú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 3-java-servlet-web-app/3-Authorization-II/roles

Em alternativa, navegue até ao repositório ms-identity-msal-java-samples, transfira-o como ficheiro .zip e extraia-o para o seu 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.

Registe a aplicação de exemplo no seu tenant 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 pretende criar as suas aplicações

Para escolher o seu inquilino, siga os seguintes passos:

Inicie sessão no portal do Azure.
Se a sua conta estiver presente em mais de um inquilino do Microsoft Entra ID, selecione o seu perfil no canto do portal do Azure e, em seguida, selecione Alternar diretório para mudar a sua sessão para o inquilino do Microsoft Entra ID pretendido.

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

Primeiro, registe uma nova aplicação no portal do Azure, seguindo as instruções em Início Rápido: Registar uma aplicação com a plataforma de identidades da Microsoft.

Em seguida, use as seguintes etapas para concluir o registro:

Aceda à página Registos de aplicações da plataforma de identidade da Microsoft para programadores.
Selecione Novo registo.
Na página Registrar um aplicativo exibida, insira as seguintes informações de registro do aplicativo:
- Na secção Name, introduza um nome descritivo para a aplicação para ser apresentado aos utilizadores da aplicação - por exemplo, .
- Em Tipos de conta suportados, selecione uma das seguintes opções:
  - Selecione Contas apenas neste diretório organizacional se estiver a criar uma aplicação para ser utilizada apenas por utilizadores no seu inquilino - isto é, uma aplicação de um único inquilino.
- Na secção URI de redirecionamento, selecione Web na caixa de combinação e introduza o seguinte URI de redirecionamento: .
Selecione Registar para criar a aplicação.
Na página de registo da aplicação, localize e copie o valor de ID da aplicação (cliente) para utilizar mais tarde. Você usa esse valor no(s) arquivo(s) de configuração do seu aplicativo.
Selecione Guardar para guardar as alterações.
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.
Na secção Segredos de cliente, selecione Novo segredo de cliente.
Digite uma descrição - por exemplo, segredo do aplicativo.
Selecione uma expiração para o segredo ou especifique um tempo de vida personalizado. Os segredos dos clientes têm uma duração máxima de 24 meses, e a Microsoft recomenda uma expiração inferior a 12 meses. Para aplicações de produção, prefira um certificado ou uma credencial federada de identidade em vez de um segredo do cliente.
Selecione Adicionar. O valor gerado é exibido.
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:

Ainda no mesmo registro de aplicativo, selecione Funções do aplicativo no painel de navegação.
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 Value, insira PrivilegedAdmin.
- Para Descrição, introduza PrivilegedAdmins que podem ver a Página de administração.
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.
- Para Valor, introduza RegularUser.
- Em Descrição, introduza Utilizadores Regulares que podem visualizar a Página do Utilizador.
Selecione Aplicar para guardar as alterações.

Atribuir usuários às funções do aplicativo

Para adicionar utilizadores à função da aplicação definida anteriormente, siga as orientações aqui: Atribuir utilizadores e grupos a funções.

Configure a aplicação (java-servlet-webapp-roles) para utilizar o registo da sua aplicação

Use as seguintes etapas para configurar o aplicativo:

Nota

Nos passos seguintes, corresponde a ou .

Abra o projeto no seu IDE.
Abra o ficheiro authentication.properties.
Encontre a cadeia de caracteres . Substitua o valor existente pelo ID de locatário do Microsoft Entra ID.
Localize a cadeia e substitua o valor existente pelo ID da aplicação ou da aplicação , copiados do portal do Azure.
Localize a cadeia e substitua o valor existente pelo valor que guardou durante a criação da aplicação , no portal do Azure.
Encontre a propriedade e certifique-se de que o valor está definido como , ou substitua pelos nomes das suas funções específicas.

Criar o exemplo

Para criar o exemplo usando o Maven, navegue até o diretório que contém o arquivo pom.xml para o exemplo e execute o seguinte comando:

mvn clean package

Este comando gera um arquivo .war que você pode executar em vários servidores de aplicativos.

Executar o exemplo

Estas instruções pressupõem que você instalou o WebSphere e configurou um servidor. Pode utilizar as orientações em Implementar um cluster do WebSphere Application Server (tradicional) em Máquinas Virtuais do Azure para uma configuração básica do servidor.

Antes de implantar no WebSphere, use as seguintes etapas para fazer algumas alterações de configuração no próprio exemplo e, em seguida, compilar ou reconstruir o pacote:

Aceda ao ficheiro authentication.properties da sua aplicação e altere o valor de para o URL do seu servidor e o número da porta que tenciona utilizar, conforme mostrado no exemplo seguinte:

# app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<server-url>:<port-number>/msal4j-servlet-auth/

Depois de salvar esse arquivo, use o seguinte comando para reconstruir seu aplicativo:
```
mvn clean package
```
Depois de a compilação do código terminar, copie o ficheiro .war para o sistema de ficheiros do servidor de destino.

Você também precisa de fazer a mesma alteração no registo da aplicação do Azure, onde o define no portal do Azure como valor de URI de redirecionamento no separador Autenticação.

Aceda à página Registos de aplicações da plataforma de identidade da Microsoft para programadores.
Utilize a caixa de pesquisa para procurar o registo da sua aplicação - por exemplo, .
Abra o registro do aplicativo selecionando seu nome.
Selecione Autenticação a partir do menu.
Na secção WebURIs de redirecionamento, selecione Adicionar URI.
Preencha o URI da sua aplicação, acrescentando /auth/redirect — por exemplo, .
Selecione Guardar.

Use as seguintes etapas para implantar o exemplo usando o Console de Soluções Integradas do WebSphere:

Na guia Aplicativos, selecione Novo Aplicativo e, em seguida, Novo Aplicativo Empresarial.
Escolha o ficheiro .war que criou e, em seguida, selecione Seguinte até chegar ao passo de instalação Map context roots for Web modules. As outras configurações padrão devem ser boas.
Para a raiz de contexto, defina-a com o mesmo valor que aparece a seguir ao número da porta no 'URI de redirecionamento' que definiu na configuração de exemplo/no registo da aplicação no Azure. Ou seja, se o URI de redirecionamento for , então a raiz de contexto deve ser .
Selecione Concluir.
Depois de a aplicação concluir a instalação, vá para a secção aplicações empresariais do WebSphere do separador Aplicações.
Selecione o arquivo .war que você instalou na lista de aplicativos e, em seguida, selecione Iniciar para implantar.
Depois de a implantação terminar, aceda a e deverá conseguir ver a aplicação.

Ver o exemplo

Use as seguintes etapas para explorar o exemplo:

Observe o status de entrada ou saída exibido no centro da tela.
Selecione o botão sensível ao contexto no canto. Este botão apresenta Iniciar sessão quando executa a aplicação pela primeira vez.
Na página seguinte, siga as instruções e entre com uma conta no locatário do Microsoft Entra ID.
Na tela de consentimento, observe os escopos que estão sendo solicitados.
Observe que o botão sensível ao contexto agora diz Sair e exibe seu nome de usuário.
Selecione Detalhes do token de ID para ver algumas das declarações descodificadas do token de ID.
Selecione Apenas administradores para ver a página . Apenas os utilizadores com a função da aplicação podem ver esta página. Caso contrário, uma mensagem de falha de autorização será exibida.
Selecione Regular Users para ver a página . Apenas os utilizadores com a função na aplicação ou podem ver esta página. Caso contrário, uma mensagem de falha de autorização será exibida.
Use o botão no canto para sair.

Sobre o código

Este exemplo utiliza o MSAL para Java (MSAL4J) para autenticar um utilizador e obter um token de identificação que pode conter a afirmação de funções. Com base na declaração de funções presente, o utilizador com sessão iniciada pode aceder a nenhuma, a uma ou a ambas as páginas protegidas, e .

Se quiser replicar o comportamento deste exemplo, você pode copiar o arquivo pom.xml e o conteúdo das pastas helpers e authservlets na pasta src/main/java/com/microsoft/azuresamples/msal4j . Também precisa do ficheiro authentication.properties. Essas classes e arquivos contêm código genérico que você pode usar em uma ampla variedade de aplicativos. Você também pode copiar o restante do exemplo, mas as outras classes e arquivos são criados especificamente para abordar o objetivo deste exemplo.

Conteúdos

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

Ficheiro/pasta	Descrição
src/main/java/com/microsoft/azuresamples/msal4j/roles/	Este diretório contém as classes que definem a lógica de negócios de back-end do aplicativo.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/	Este diretório contém as classes que são usadas para entrar e sair pontos de extremidade.
*Servlet.java	Todos os endpoints disponíveis são definidos em classes Java com nomes terminados em `Servlet`.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/	Classes auxiliares para autenticação.
AuthenticationFilter.java	Redireciona pedidos não autenticados para endpoints protegidos para a página 401.
src/main/resources/authentication.properties	Microsoft Entra ID e configuração do programa.
src/main/webapp/	Este diretório contém os modelos UI - JSP
CHANGELOG.md	Lista de alterações à amostra.
CONTRIBUTING.md	Orientações para contribuir para a amostra.
LICENÇA	A licença para a amostra.

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": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

É criada uma instância de no ficheiro AuthHelper.java, conforme mostrado no exemplo seguinte. Esse objeto ajuda a criar a URL de autorização do Microsoft Entra e também ajuda a trocar o token de autenticação por um token de acesso.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Os seguintes parâmetros são usados para instanciação:

A ID do cliente do aplicativo.
O segredo do cliente, que é um requisito para aplicações cliente confidenciais.
A Autoridade de ID do Microsoft Entra, que inclui sua ID de locatário do Microsoft Entra.

Neste exemplo, esses valores são lidos do arquivo authentication.properties usando um leitor de propriedades no arquivo Config.java .

Guia passo a passo

As etapas a seguir fornecem um passo a passo da funcionalidade do aplicativo:

O primeiro passo do processo de início de sessão é enviar um pedido para o ponto final no seu inquilino do Microsoft Entra ID. A instância da MSAL4J é usada para construir um URL de pedido de autorização. A aplicação redireciona o navegador para este URL, que é onde o utilizador inicia sessão.
```
final ConfidentialClientApplication client = getConfidentialClientInstance();
AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
        .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
contextAdapter.redirectUser(authorizeUrl);
```
A lista a seguir descreve os recursos desse código:
- : Parâmetros que têm de ser definidos para construir um AuthorizationRequestUrl.
- : Onde o Microsoft Entra ID redireciona o navegador — juntamente com o código de autenticação — depois de recolher as credenciais do utilizador. Ele deve corresponder ao URI de redirecionamento no registo da aplicação Microsoft Entra ID no Azure portal.
- : Scopes são as permissões solicitadas pela aplicação.
  - Normalmente, os três âmbitos são suficientes para receber uma resposta de token de ID.
  - A lista completa dos âmbitos solicitados pela aplicação pode ser consultada no ficheiro authentication.properties. Você pode adicionar mais escopos, como .
Ao utilizador é apresentado um pedido de início de sessão pelo Microsoft Entra ID. Se a tentativa de início de sessão for bem-sucedida, o navegador do utilizador é redirecionado para o ponto final de redirecionamento da aplicação. Um pedido válido para este ponto final contém um código de autorização.

A instância troca então este código de autorização por um token de ID e um token de acesso junto do Microsoft Entra ID.

// First, validate the state, then parse any error codes in response, then extract the authCode. Then:
// build the auth code params:
final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
        .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();

// Get a client instance and leverage it to acquire the token:
final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
final IAuthenticationResult result = client.acquireToken(authParams).get();

A lista a seguir descreve os recursos desse código:

: Parâmetros que devem ser configurados para trocar o Código de Autorização por um ID e/ou um token de acesso.
: O código de autorização recebido na extremidade de redirecionamento.
: O URI de redirecionamento utilizado no passo anterior deve ser fornecido novamente.
: Os escopos utilizados no passo anterior devem ser passados novamente.

Se for bem-sucedida, as declarações associadas ao token são extraídas. Se a verificação do nonce for bem-sucedida, os resultados são colocados em - uma instância de - e guardados na sessão. A aplicação pode então instanciar o a partir da sessão, por meio de uma instância de , sempre que precisar de aceder ao mesmo, conforme mostrado no código seguinte:

// parse IdToken claims from the IAuthenticationResult:
// (the next step - validateNonce - requires parsed claims)
context.setIdTokenClaims(result.idToken());

// if nonce is invalid, stop immediately! this could be a token replay!
// if validation fails, throws exception and cancels auth:
validateNonce(context);

// set user to authenticated:
context.setAuthResult(result, client.tokenCache().serialize());

Proteja as rotas

Para obter informações sobre como o aplicativo de exemplo filtra o acesso a rotas, consulte AuthenticationFilter.java. No ficheiro authentication.properties, a propriedade contém as rotas separadas por vírgulas a que só os utilizadores autenticados podem aceder, conforme mostrado no exemplo seguinte:

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

As rotas listadas nos conjuntos de regras separados por vírgulas em também não estão acessíveis a utilizadores não autenticados, conforme mostrado no exemplo seguinte. No entanto, estas rotas também contêm uma lista de pertenças a funções da aplicação, separada por espaços: apenas os utilizadores com pelo menos uma das funções correspondentes podem aceder a estas rotas depois de se autenticarem.

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

Âmbitos

Escopos indicam ao Microsoft Entra ID o nível de acesso que a aplicação está a pedir.

Com base nos escopos solicitados, o Microsoft Entra ID apresenta uma caixa de diálogo de consentimento ao usuário ao entrar. Se o utilizador der o seu consentimento a um ou mais âmbitos e obtiver um token, os âmbitos aos quais foi dado consentimento ficam codificados no .

Para os escopos solicitados pela aplicação, consulte authentication.properties. Esses três escopos são solicitados pela MSAL e fornecidos pelo ID do Microsoft Entra por padrão.

Mais informações

Biblioteca de Autenticação da Microsoft (MSAL) para Java
Plataforma de identidade da Microsoft
Início Rápido: Registar uma aplicação na plataforma de identidade da Microsoft
Compreender as experiências de consentimento da aplicação no Microsoft Entra ID
Compreender o consentimento do utilizador e do administrador
Exemplos de código MSAL
Como adicionar funções da aplicação à sua aplicação e recebê-las no token
Gerir a atribuição de utilizadores a uma aplicação no Microsoft Entra ID

Próximo passo

Implementar aplicações WebSphere Java no Traditional WebSphere nas Máquinas Virtuais do Azure

Comentários

Esta página foi útil?

Última atualização a 2026-09-17