Proteja aplicativos Quarkus com o Microsoft Entra ID usando o OpenID Connect

Este artigo mostra como proteger aplicativos do Red Hat Quarkus com o Microsoft Entra ID usando o OpenID Connect (OIDC).

Neste artigo, você aprenderá como:

• Configure um provedor OpenID Connect com o Microsoft Entra ID.
• Proteja um aplicativo Quarkus usando o OpenID Connect.
• Executar e testar o aplicativo Quarkus.

Pré-requisitos

• Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
• Uma identidade do Azure com pelo menos a função de Administrador de Aplicativos de Nuvem do Microsoft Entra. Para obter mais informações, consulte Listar atribuições de função do Microsoft Entra e as funções internas do Microsoft Entra.
• Um locatário do Microsoft Entra. Se você não tiver um locatário existente, consulte Início Rápido: configurar um locatário.
• Um computador local com sistema operacional semelhante ao Unix instalado, por exemplo, Ubuntu, macOS ou do Subsistema do Windows para Linux.
• Git.
• Uma implementação do Java SE, versão 21 ou posterior, por exemplo, o build da Microsoft do OpenJDK.
• Maven, versão 3.9.3 ou posterior.

Configure um provedor OpenID Connect com o Microsoft Entra ID

Nesta seção, você configura um provedor OpenID Connect com o Microsoft Entra ID para uso com seu aplicativo Quarkus. Em uma seção posterior, você configura o aplicativo Quarkus usando o OpenID Connect para autenticar e autorizar usuários em seu locatário do Microsoft Entra.

Criar usuários no locatário no Microsoft Entra

Primeiro, crie dois usuários em seu locatário do Microsoft Entra seguindo as etapas em Como criar, convidar e excluir usuários. Você só precisa da seção Criar um usuário. Use as instruções a seguir ao longo do artigo e, em seguida, retorne a este artigo depois de criar usuários em seu locatário do Microsoft Entra.

Para criar um usuário para atuar como "administrador" no aplicativo, use as seguintes etapas:

1. Quando você acessar a guia Básico na seção Criar um usuário, use as seguintes etapas:

   1. Para Nome UPN, insira administrador. Salve o valor para que você possa usá-lo mais tarde ao entrar no aplicativo.

   2. Para Apelido de email, selecione Derivar do nome UPN

   3. Para Nome de exibição, insira Administrador.

   4. Para Senha, selecione Gerar senha automaticamente. Copie e salve o valor da Senha para usar mais tarde ao entrar no aplicativo.

   5. Selecione Conta habilitada.

      

   6. Selecione Examinar + criar>Criar. Aguarde até que o usuário seja criado.

   7. Aguarde cerca de um minuto e selecione Atualizar. Você deve ver o novo usuário na lista.

Para criar um usuário para servir como um "usuário" no aplicativo, repita essas etapas, mas use os seguintes valores:

• Para Nome UPN, insira usuário.
• Para Nome de exibição, insira Usuário.

Registrar um aplicativo no Microsoft Entra ID

Em seguida, registre um aplicativo seguindo as etapas mostradas em Início Rápido: registrar um aplicativo com a plataforma de identidade da Microsoft. Use as instruções a seguir ao ler o artigo e, em seguida, retorne a este artigo depois de registrar e configurar o aplicativo.

1. Quando você chegar à seção Registrar um aplicativo, use as seguintes etapas:
   1. Para Tipos de contas com suporte, selecione Contas somente neste diretório organizacional (somente o diretório padrão – locatário único).
   2. Quando o registro terminar, salve os valores de ID do Aplicativo (cliente) e de ID do Diretório (locatário) para usar posteriormente na configuração do aplicativo.
2. Quando você chegar à seção Adicionar um URI de redirecionamento, ignore as etapas por ora. Você adicionará o URI de redirecionamento posteriormente ao executar e testar o aplicativo de exemplo de forma local neste artigo.
3. Quando você chegar à seção Adicionar credenciais, selecione a guia Adicionar um segredo do cliente.
4. Ao adicionar um segredo do cliente, anote o valor de Segredo do cliente a ser usado posteriormente na configuração do aplicativo.

Adicionar funções de aplicativo no seu aplicativo

Em seguida, adicione funções de aplicativo ao seu aplicativo seguindo as etapas em Adicionar funções de aplicativo ao seu aplicativo e receba-as no token. Você só precisa das seções Declarar funções para um aplicativo e Atribuir usuários e grupos a funções do Microsoft Entra. Use as instruções a seguir ao longo do artigo e, em seguida, retorne a este artigo depois de declarar funções para o aplicativo.

1. Quando você acessar a seção Declarar funções para um aplicativo, use a interface do usuário de Funções do aplicativo para criar funções para o administrador e o usuário comum.

   1. Crie uma função de usuário administrador usando os seguintes valores:

      • Para Nome de exibição, insira Administrador.
      • Para Tipos de membros permitidos:, selecione Usuários/Grupos.
      • Em Valor, insira admin.
      • Para Descrição, insira Administrador.
      • Selecione Deseja habilitar esta função de aplicativo?.

      

   2. Escolha Aplicar. Aguarde até que a função seja criada.

   3. Crie uma função de usuário regular usando as mesmas etapas, mas com os seguintes valores:

      • Para Nome de exibição, insira Usuário.
      • Para Valor, insira usuário.
      • Para Descrição, insira Usuário.

      

2. Quando você acessar a seção Atribuir usuários e grupos a funções do Microsoft Entra, use as seguintes etapas:

   1. Selecione Adicionar usuário/grupo.

   2. No painel Adicionar Atribuição, para Usuários, selecione usuário Administrador e, para Selecionar uma função, selecione a função Administrador. Em seguida, selecione Atribuir. Aguarde até que a atribuição do aplicativo seja bem-sucedida. Talvez seja necessário rolar a tabela para o lado para ver a coluna Função atribuída.

   3. Repita as etapas anteriores para atribuir a função Usuário ao usuário Usuário.

   4. Selecione Atualizar e você verá os usuários e funções atribuídos no painel Usuários e grupos.

      

      Talvez seja necessário ajustar a largura dos cabeçalhos das colunas para que sua exibição se pareça com a imagem.

Não siga nenhuma outra etapa em Adicionar funções de aplicativo ao seu aplicativo e receba-as no token.

Proteja um aplicativo Quarkus usando o OpenID Connect

Nesta seção, você protege um aplicativo Quarkus que autentica e autoriza usuários em seu locatário do Microsoft Entra usando o OpenID Connect. Você também aprende a dar aos usuários acesso a determinadas partes do aplicativo usando o RBAC (controle de acesso baseado em função).

O aplicativo Quarkus de exemplo para este início rápido está no GitHub no repositório quarkus-azure e localizado no diretório entra-id-quarkus.

Habilitar autenticação e autorização para proteger o aplicativo

O aplicativo tem um recurso de página de boas-vindas definido em WelcomePage.java, que é mostrado no código de exemplo a seguir. Esta página pode ser acessada por usuários não autenticados. O caminho raiz da página de boas-vindas está em /.

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

Na página de boas-vindas, os usuários podem entrar no aplicativo para acessar a página de perfil. A página de boas-vindas tem links para entrar como usuário ou administrador. Os links estão em /profile/user e /profile/admin, respectivamente. A interface do usuário da página de boas-vindas é definida em welcome.qute.html e mostrada no exemplo a seguir:

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

Os links /profile/user e /profile/admin apontam para o recurso de página de perfil, definido em ProfilePage.java, conforme mostrado no código de exemplo a seguir. Esta página é acessível apenas para usuários autenticados usando a anotação @RolesAllowed("**") do pacote jakarta.annotation.security.RolesAllowed. A anotação @RolesAllowed("**") especifica que somente usuários autenticados podem acessar o caminho /profile.

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

O recurso de página de perfil habilita o RBAC usando a anotação @RolesAllowed. Os argumentos para a anotação @RolesAllowed especificam que somente os usuários com a função admin podem acessar o caminho /profile/admin e os usuários com a função user ou admin podem acessar o caminho /profile/user.

Os pontos de extremidade /profile/admin e /profile/user retornam a página de perfil. A interface do usuário da página de perfil é definida em profile.qute.html, conforme mostrado no exemplo a seguir. Esta página exibe o nome, as funções e os escopos do usuário. A página de perfil também tem um link de saída em /logout, que redireciona o usuário para o provedor OIDC para sair. A página de perfil é escrita usando o mecanismo de modelagem Qute. Observe o uso de expressões {} na página. Essas expressões usam os valores passados para o TemplateInstance usando o método data(). Para obter mais informações sobre o Qute, consulte Mecanismo de modelagem do Qute.

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

Depois de sair, o usuário é redirecionado para a página de boas-vindas e pode entrar novamente.

Executar e testar o aplicativo Quarkus

Nesta seção, você executa e testa o aplicativo Quarkus para ver como ele funciona com o Microsoft Entra ID como o provedor OpenID Connect.

Adicionar um URI de redirecionamento ao registro do aplicativo

Para executar e testar o aplicativo localmente com êxito, você precisará adicionar um URI de redirecionamento ao registro do aplicativo. Siga as instruções na seção Adicionar um URI de redirecionamento do Início Rápido: Registrar um aplicativo com a plataforma de Identidade da Microsoft e use os seguintes valores:

• Para Configurar plataformas, selecione Web.
• Em URIs de redirecionamento, insira http://localhost:8080.

Preparar o exemplo

Use as etapas a seguir para preparar o aplicativo Quarkus de exemplo:

1. Use os comandos a seguir para clonar o aplicativo Quarkus de exemplo do GitHub e navegue até o diretório entra-id-quarkus:

   git clone https://github.com/Azure-Samples/quarkus-azure
   cd quarkus-azure/entra-id-quarkus
   git checkout 2024-09-26
   

   Se você vir uma mensagem sobre estar no estado HEAD desanexado, essa mensagem pode ser ignorada com segurança. Como esse artigo não requer nenhum commit, o estado HEAD desanexado é apropriado.

2. Use os seguintes comandos para definir as seguintes variáveis de ambiente com os valores anotados anteriormente:

   export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
   export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
   export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0
   

   Essas variáveis de ambiente fornecem os valores para o suporte integrado do OpenID Connect no Quarkus. As propriedades correspondentes em application.properties são mostradas no exemplo a seguir.

   quarkus.oidc.client-id=
   quarkus.oidc.credentials.secret=
   quarkus.oidc.auth-server-url=
   

   Se o valor de uma propriedade estiver em branco no application.properties, o Quarkus converterá o nome da propriedade em uma variável de ambiente e lerá o valor do ambiente. Para obter detalhes sobre a conversão de nomenclatura, consulte a especificação do MicroProfile Config.

Execute o aplicativo Quarkus

Você pode executar o aplicativo Quarkus em diferentes modos. Selecione um dos seguintes métodos para executar o aplicativo Quarkus. Para permitir que o Quarkus se conecte ao Microsoft Entra ID, certifique-se de executar o comando no shell no qual você definiu as variáveis de ambiente mostradas na seção anterior.

• Execute o aplicativo Quarkus no modo de desenvolvimento:

  mvn quarkus:dev
  

• Execute o aplicativo Quarkus no modo JVM:

  mvn install
  java -jar target/quarkus-app/quarkus-run.jar
  

• Execute o aplicativo Quarkus no modo nativo:

  mvn install -Dnative -Dquarkus.native.container-build
  ./target/quarkus-ad-1.0.0-SNAPSHOT-runner
  

Se você quiser experimentar modos diferentes, use Ctrl+C para interromper o aplicativo Quarkus e, em seguida, execute o aplicativo Quarkus em outro modo.

Testar o aplicativo Quarkus

Depois que o aplicativo Quarkus estiver em execução, abra um navegador da Web com uma guia privada e navegue até http://localhost:8080. Você deve ver a página de boas-vindas com links para entrar como usuário ou um administrador. O uso de uma guia privada evita poluir qualquer atividade existente do Microsoft Entra ID que você possa ter em seu navegador normal.

Reunir as credenciais para os dois usuários

Neste artigo, o Microsoft Entra ID usa o endereço de email de cada usuário como a ID de usuário para entrar. Use as etapas a seguir para obter o endereço de e-mail do usuário administrador e do usuário comum:

1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
2. Se você tiver acesso a vários locatários, use o ícone de Configurações icon ( ) no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
3. Navegue até Identidade > Usuários > Todos os Usuários.
4. Localize o usuário administrador na lista e selecione-o.
5. Localize o campo Nome UPN.
6. Use o ícone de cópia ao lado do valor do campo para salvar o endereço de email do usuário na área de transferência. Salve o valor para usar depois.
7. Para obter o endereço de email do usuário comum, siga as mesmas etapas.

Use as senhas do usuário administrador e do usuário regular que você definiu ao criar os usuários.

Exercite a funcionalidade do aplicativo

Use as seguintes etapas para exercer a funcionalidade:

1. Selecione o link Entrar como usuário. Entre com o usuário normal criado anteriormente. Depois de entrar, o Microsoft Entra ID redireciona você para a página de perfil, onde você vê seu nome, funções e escopos.

   

2. Se esta for a primeira vez que você entra, será solicitado que você atualize sua senha. Siga as instruções para atualizar sua senha.

3. Se você for solicitado com Sua organização requer informações de segurança adicionais. Siga as instruções para baixar e configurar o aplicativo Microsoft Authenticator, você pode selecionar Perguntar mais tarde para continuar o teste.

4. Se você for solicitado com Permissões solicitadas, revise as permissões solicitadas pelo aplicativo. Selecione Aceitar para continuar o teste.

5. Selecione Sair para sair do aplicativo Quarkus. O Microsoft Entra ID executa a saída. Depois de sair, o Microsoft Entra ID redireciona você para a página de boas-vindas.

6. Selecione o link Entrar como administrador. O Microsoft Entra ID redireciona você para a página de entrada. Entre com o usuário administrador criado anteriormente. Depois de entrar, o Microsoft Entra ID redireciona você para a página de perfil semelhante, com uma função admin diferente.

   

7. Saia novamente e tente Entrar como administrador com o usuário comum que você criou anteriormente. Você deve ver uma mensagem de erro porque o usuário comum não tem a função admin.

   

Limpar os recursos

Este artigo não direciona você para implantar seu aplicativo no Azure. Não há recursos do Azure para limpar o aplicativo, embora haja recursos do Microsoft Entra ID. Para implantar um aplicativo no Azure, você pode seguir as diretrizes referenciadas na próxima seção.

Quando você terminar com os recursos para este aplicativo de exemplo, use as etapas a seguir para limpar os recursos do Microsoft Entra ID. A remoção de recursos não utilizados do Microsoft Entra ID é uma prática recomendada de segurança importante.

1. Remova o registro do aplicativo que você criou seguindo as etapas em Remover um aplicativo registrado na plataforma de identidade da Microsoft. Você só precisa seguir as etapas na seção Remover um aplicativo criado por sua organização.
2. O ato de remover o registro do aplicativo também deve excluir o aplicativo empresarial. Para obter mais informações sobre como excluir aplicativos empresariais, consulte Excluir um aplicativo empresarial.
3. Exclua os usuários que você criou seguindo as etapas em Como criar, convidar e excluir usuários.

Próximas etapas

Neste início rápido, você protege os aplicativos do Quarkus com o Microsoft Entra ID usando o OpenID Connect. Para saber mais, explore os seguintes recursos:

• Implantar um aplicativo Java com o Quarkus em Aplicativos de Contêiner do Azure
• Autenticação do OpenID Connect com a ID do Microsoft Entra
• Plataforma de identidade da Microsoft e fluxo de código de autorização do OAuth 2.0
• Proteger um aplicativo Web usando o fluxo de código de autorização do OIDC (OpenId Connect)
• Mecanismo de fluxo de código de autorização do OpenID Connect para proteger Aplicativos Web
• Propriedades de configuração do OIDC (OpenID Connect)