Partilhar via

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

  • Artigo

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

Neste artigo, vai aprender a:

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

Pré-requisitos

Configurar 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 do 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 novo 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 servir como "administrador" no aplicativo, use as seguintes etapas:

  1. Quando chegar à guia Noções básicas na seção Criar um novo usuário , use as seguintes etapas:

    1. Em Nome principal do usuário, digite admin. Salve o valor para poder usá-lo mais tarde quando entrar no aplicativo.

    2. Em Apelido do email, selecione Derivar do nome principal do usuário

    3. Em Nome para exibição, digite Admin.

    4. Em Senha, selecione Gerar senha automaticamente. Copie e guarde o valor Palavra-passe para utilizar mais tarde quando iniciar sessão na aplicação.

    5. Selecione Conta ativada.

      Captura de ecrã do portal do Azure que mostra o painel Criar novo utilizador Noções básicas para um utilizador administrador.

    6. Selecione Rever + 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 estas etapas, mas use os seguintes valores:

  • Em Nome principal do usuário, digite usuário.
  • Em Nome para exibição, digite Usuário.

Captura de ecrã do portal do Azure que mostra o painel Criar novo utilizador Noções básicas para um utilizador normal.

Registar uma aplicação no Microsoft Entra ID

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

  1. Quando chegar à seção Registrar um aplicativo , use as seguintes etapas:
    1. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional (Somente diretório padrão - Locatário único).
    2. Quando o registro terminar, salve os valores de ID do aplicativo (cliente) e ID do diretório (locatário) para usar posteriormente na configuração do aplicativo.
  2. Quando chegar à seção Adicionar um URI de redirecionamento, ignore as etapas como por enquanto. Você adiciona o URI de redirecionamento mais tarde quando executa e testa o aplicativo de exemplo localmente neste artigo.
  3. Quando chegar à seção Adicionar credenciais, selecione a guia Adicionar um segredo do cliente.
  4. Ao adicionar um segredo do cliente, anote o valor Segredo do cliente para usar posteriormente na configuração do aplicativo.

Adicionar funções de aplicativo ao 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 chegar à seção Declarar funções para um aplicativo, use a interface do usuário Funções do aplicativo para criar funções para o administrador e o usuário regular.

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

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

      Captura de ecrã do portal do Azure que mostra o painel Criar função de aplicação para o utilizador administrador.

    2. Selecione 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:

      • Em Nome para exibição, digite Usuário.
      • Em Valor, insira usuário.
      • Em Descrição, digite Usuário.

      Captura de ecrã do portal do Azure que mostra o painel Criar função de aplicação para o utilizador normal.

  2. Quando chegar à 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 Administrador da função. Em seguida, selecione Atribuir. Aguarde até que a atribuição do aplicativo seja bem-sucedida. Talvez seja necessário rolar a tabela para os lados 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 .

      Captura de ecrã do portal do Azure que mostra os utilizadores e funções atribuídos.

      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 controle de acesso baseado em função (RBAC).

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 é acessível a utilizadores 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 como 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>

Ambos os /profile/user links e /profile/admin links 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 a usuários autenticados usando a @RolesAllowed("**") anotação do jakarta.annotation.security.RolesAllowed pacote. A @RolesAllowed("**") anotação especifica que apenas usuários autenticados podem acessar o /profile caminho.

@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 @RolesAllowed anotação. Os argumentos para a @RolesAllowed anotação especificam que somente os usuários com a admin função podem acessar o caminho e os /profile/admin usuários com a user função ou admin podem acessar o /profile/user caminho.

Os pontos de /profile/admin extremidade 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 no /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 fazem uso dos valores passados para o TemplateInstance uso do data() método. Para obter mais informações sobre Qute, consulte Mecanismo de modelagem 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>

Após 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ê precisa adicionar um URI de redirecionamento ao registro do aplicativo. Siga as instruções na seção Adicionar um URI de redirecionamento do Guia de início rápido: registre um aplicativo com a plataforma de identidade da Microsoft e use os seguintes valores:

  • Em Configurar plataformas, selecione Web.
  • Para Redirecionar URIs, digite http://localhost:8080.

Preparar a amostra

Use as seguintes etapas para preparar o aplicativo Quarkus de exemplo:

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

    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 é segura para ignorar. Como este artigo não requer nenhuma confirmação, o estado HEAD destacado é apropriado.

  2. Use os comandos a seguir para definir as seguintes variáveis de ambiente com os valores que você anotou 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 interno 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 application.properties, o Quarkus converte o nome da propriedade em uma variável de ambiente e lê o valor do ambiente. Para obter detalhes sobre a conversão de nomenclatura, consulte a especificação MicroProfile Config.

Executar 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, execute 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 parar 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 como administrador. Usar uma guia privada evita poluir qualquer atividade existente do Microsoft Entra ID que você possa ter em seu navegador regular.

Captura de tela do aplicativo de exemplo que mostra a página de boas-vindas.

Reúna as credenciais dos dois usuários

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

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

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

Exercer a funcionalidade do aplicativo

Use as seguintes etapas para exercer a funcionalidade:

  1. Selecione o link Entrar como usuário . Inicie sessão com o utilizador normal que criou anteriormente. Depois de iniciar sessão, o Microsoft Entra ID redireciona-o para a página de perfil, onde vê o seu nome, funções e âmbitos.

    Captura de tela do aplicativo de exemplo que mostra o perfil do usuário.

  2. Se esta for a primeira vez que inicia sessão, ser-lhe-á pedido que atualize a sua palavra-passe. Siga as instruções para atualizar a sua palavra-passe.

  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 lhe for pedido Permissões solicitadas, reveja as permissões solicitadas pela aplicação. Selecione Aceitar para continuar o teste.

  5. Selecione Sair para sair do aplicativo Quarkus. O Microsoft Entra ID executa o logout. 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. Inicie sessão com o utilizador administrador que criou anteriormente. Depois de iniciar sessão, o Microsoft Entra ID redireciona-o para a página de perfil semelhante, com uma função admindiferente.

    Captura de tela do aplicativo de exemplo que mostra o perfil de administrador.

  7. Termine sessão novamente e tente iniciar sessão como administrador com o utilizador normal que criou anteriormente. Você verá uma mensagem de erro porque o usuário regular não tem a admin função.

    Captura de tela do aplicativo de exemplo que mostra a mensagem de acesso negado.

Clean up resources (Limpar recursos)

Este artigo não direciona você a 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 orientações mencionadas na próxima seção.

Quando 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 de 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 pela 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 corporativos, consulte Excluir um aplicativo empresarial.
  3. Exclua os usuários criados seguindo as etapas em Como criar, convidar e excluir usuários.

Próximos passos

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