Utilização do KeyCloak em aplicações NET 6.0

Olá pessoal, como vão?

Na maioria de nossas aplicações, precisamos sempre utilizar autenticação e autorização de usuários (JWT, OpenID…), e muitas das vezes sempre escrevemos o mesmo código em todos os nossos sistemas;

Escrevo hoje para falar do KeyCloak. Não é nenhuma novidade, pois ele existe há pelo menos uns 5 anos, mas existem várias pessoas que ainda não o conhecem, e por isso resolvi mostrar o seu funcionamento;

O que é o KeyCloak

O Keycloak é um produto de software de código aberto, mantido pela RedHat, para permitir o logon único com gerenciamento de identidade e acesso voltado para aplicativos e serviços modernos. (Fonte Wikipedia)

Então agora, irei demonstrar um passo a passo de como utilizar o KeyCloak em suas aplicações;

Inicialmente, é bom explicar que ele por ser código aberto, é gratuito para você instalar em sua infraestrutura de forma standalone, você pode olhar aqui https://www.keycloak.org/downloads, quais as opções que pode utilizar;

Demo

Mas aqui para o nosso exemplo, vamos utilizar uma imagem Docker do KeyCloak. Para isso execute esse comando para a execução da imagem

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.2 start-dev

Depois disso coloque no browser o link: http://localhost:8080

Irá abrir o portal administrativo do KeyCloak, coloque o usuário(admin) e senha(admin), para que possamos configurar os usuários que terão acesso a nossa aplicação;

Primeiro, vamos criar um novo Realm, uma organização para a nossa aplicação, vamos criar de nome marraia

Agora, iremos criar um client, que para aqueles que não tem um conhecimento sobre, é que cada aplicação que precisar ter a autorização e autenticação de usuários, necessariamente precisa estar cadastrada no KeyCloak. Onde depois de cadastrada, o KeyCloak oferece um identificador que devemos colocar nas configurações de nossa aplicação, para que ela possa se autenticar no KeyCloak

Clique no menu Clients, e depois clique no botão Create Client

Vamos criar com o nome marraia-api e depois clique em Next

Na segunda tela, habilite a opção Client authentication e clique em Salvar.

Seguindo com as configurações, precisamos criar um Client Scope, para que quando o usuário obter a autenticação ao KeyCloak, será gerado um token, e esse token deve ser enviado a aplicação, e a aplicação deverá validar se o token gerado, realmente foi gerado pelo servidor de autenticação, que no nosso caso é o KeyCloak;

Clique no menu Client scopes, e depois clique em Create Client Scope

Iremos criar o scope com o nome marraia-client-scope

Importante nesse passo, colocar as opções:

Type: Default

Protocol: OpenId Connect

Include in tolen scope: habilitado

Clique em Salvar;

Depois disso, irá se habilitar duas novas abas: Mappers e Scope

Primeiro iremos criar um novo Mapper, clique na aba Mappers e clique em Create a new mapper

Clique na opção Audience, e depois coloque um nome, que em nosso exemplo será o marraia-audience e relacione o client marraia-api na opção Inclueded Client Audience.

Habilite a opção Add to access token e depois clique em Salvar;

Agora clique novamente no menu Clients, vá até a aba Clients Scope e clique em Add Client Scope

Selecione o Client Scope criado anteriormente e clique em Add com a opção Default

Agora, ainda no menu Clients no client marraia-api, clique na opção Action;

Clique na opção Download adapter config, irá aparecer essa janela

Copie o json que está no campo Details, pois iremos utilizar como configuração em nossa aplicação .Net 6.0;

Agora precisamos criar um usuário no KeyCloak, para que ele possa se autenticar;

Clique no menu Users, e clique em Create Users

Coloque os dados do usuário, para o exemplo, colocamos somente o username, first name e last name e clique em Create

Irá se habilitar varias outras abas, mas clique em Credentials e clique em Set Password, para criar uma senha a esse usuário;

Para nosso exemplo, selecionamos a opção Temporary como falsa, e depois clique em Salvar;

Depois desse passo a passo, configuramos o nosso servidor de autenticação o KeyCloak. Agora iremos criar nossa aplicação, que será uma Web Api se autenticando ao KeyCloak;

Crie uma nova WebApi em .Net 6.0 no Visual Studio, e instale essas bibliotecas do KeyCloak via nuget;

dotnet add package Keycloak.AuthServices.Authentication --version 1.2.1
dotnet add package Keycloak.AuthServices.Authorization--version 1.2.1
dotnet add package IdentityModel.AspNetCore
dotnet add package Refit.HttpClientFactory

Depois disso, pegue o json, que obtemos do client nos passos anteriores, e coloque em seu appsettings.json de sua aplicação dessa forma;

"Keycloak": {
  "realm": "marraia",
  "auth-server-url": "http://localhost:8080/",
  "ssl-required": "none",
  "resource": "marraia-api",
  "verify-token-audience": true,
  "credentials": {
    "secret": "DYlx2KgElgkOx7NMGAWcAooGwj3sJqnx"
  },
  "confidential-port": 0
}

Perceba que a opção ssl-required está marcada como none, pois como estamos rodando em container não temos aqui configurado ssl, por isso setamos como none;

Agora no arquivo Program.cs, configure dessa forma

using Keycloak.AuthServices.Authentication;
using Keycloak.AuthServices.Authorization;
using Keycloak.AuthServices.Sdk.Admin;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var authenticationOptions = builder
                            .Configuration
                            .GetSection(KeycloakAuthenticationOptions.Section)
                            .Get<KeycloakAuthenticationOptions>();

builder.Services.AddKeycloakAuthentication(authenticationOptions);

var authorizationOptions = builder
                            .Configuration
                            .GetSection(KeycloakProtectionClientOptions.Section)
                            .Get<KeycloakProtectionClientOptions>();

builder.Services.AddKeycloakAuthorization(authorizationOptions);

var adminClientOptions = builder
                            .Configuration
                            .GetSection(KeycloakAdminClientOptions.Section)
                            .Get<KeycloakAdminClientOptions>();

builder.Services.AddKeycloakAdminHttpClient(adminClientOptions);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();

Perceba, que configuramos a autenticação e autorização do KeyCloak, utilizando as configurações que estão no appsettings.json (KeycloakAuthenticationOptions.Section)

Primeiro, vamos rodar a aplicação sem colocar o [Authorize] em uma rota da API

Retorno com sucesso, pois ainda não colocamos o atributo [Authorize]. Agora iremos colocar o atributo na rota, e iremos executar, o retorno terá que ser 401 (Não autorizado);

Vamos executar e o retorno:

Agora, vamos obter o token no KeyCloak para o usuário que configuramos, para dai sim requisitar a API;

POST: http://localhost:8080/realms/marraia/protocol/openid-connect/token

Veja que colocamos, as configurações para a chamada do KeyCloak (Username, Password e Client_secret (está no corpo do json, que obtemos nos passos anteriores))

Ao executar o retorno deverá ter o token, que devemos depois adicionar no header da execução da API

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUVW5ZdDlSQWhLTThyTVZpdHZKZF9YellVaElKU2R4Qk12dzJ0TnZpcFVzIn0.eyJleHAiOjE2NzE3MjkyNzIsImlhdCI6MTY3MTcyODk3MiwianRpIjoiNmNjOTNhNTUtZjA0ZS00OTAwLWI1MDMtNmI0NzI0ZTg4ZDcxIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXJyYWlhIiwiYXVkIjpbIm1hcnJhaWEtYXBpIiwiYWNjb3VudCJdLCJzdWIiOiI2MDExOWI3ZS0xZGNmLTRmMGMtYjFjYi1lMjllZmZhNmIyNzciLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJtYXJyYWlhLWFwaSIsInNlc3Npb25fc3RhdGUiOiJkYmYxZWU1NS0wY2I1LTRhNWEtYjYxNC1lOTFiNDAyMzA2MmYiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtbWFycmFpYSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im1hcnJhaWEtY2xpZW50LXNjb3BlIGVtYWlsIHByb2ZpbGUiLCJzaWQiOiJkYmYxZWU1NS0wY2I1LTRhNWEtYjYxNC1lOTFiNDAyMzA2MmYiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIm5hbWUiOiJGZXJuYW5kbyBNZW5kZXMiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJtYXJyYWlhIiwiZ2l2ZW5fbmFtZSI6IkZlcm5hbmRvIiwiZmFtaWx5X25hbWUiOiJNZW5kZXMifQ.FaJyyV9tdxmyhNA1O_Fx1pykjc5vSbLgUy017YiXOasFc83d0CDb4XVnFfXIZjZoL74oJ-hmMuEZL6ET74G5fNmLvzuBNIKHmrdBG586Rh4CybpVnwSomcoBrxg5p_rRD21POZS2N1S6Y2O7Sm5owIdoSQFetKgPm-QFtWOEaiY0cle7aXunIHfVoxKUbXmfnRNlilrsv9-kZwc4atWeSi6Oy4aFWFqrYqUzfSF_6r9w53jeyYDneVL2N8u8_bBUhWpaJl8KwfJoWoxtiZXXe5EBGkgcvU20GLSP4_uqsv6rSPwXttW98cs9LR5Iv3ygV8MbnyLv61UGWyO4D7H0FA",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJlYWQ3MjQ3NS0wZGI4LTRiNGItOWY4Ni03ZDI4ZGM1YjA2ZTUifQ.eyJleHAiOjE2NzE3MzA3NzIsImlhdCI6MTY3MTcyODk3MiwianRpIjoiYzVjMmM3ZTYtMDliZS00MjZjLThhNmQtM2UxZDQzMDRlMTQzIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXJyYWlhIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXJyYWlhIiwic3ViIjoiNjAxMTliN2UtMWRjZi00ZjBjLWIxY2ItZTI5ZWZmYTZiMjc3IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im1hcnJhaWEtYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImRiZjFlZTU1LTBjYjUtNGE1YS1iNjE0LWU5MWI0MDIzMDYyZiIsInNjb3BlIjoibWFycmFpYS1jbGllbnQtc2NvcGUgZW1haWwgcHJvZmlsZSIsInNpZCI6ImRiZjFlZTU1LTBjYjUtNGE1YS1iNjE0LWU5MWI0MDIzMDYyZiJ9.wqCNiaJPuiXrsU3Njveey0IsWae7zqx8SYHq0N1YTaE",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "dbf1ee55-0cb5-4a5a-b614-e91b4023062f",
    "scope": "marraia-client-scope email profile"
}

Agora obtenha o campo access_token e execute a API com bearer no header da requisição;

Veja a requisição foi executada com sucesso;

Portanto, de forma fácil e simples, conseguimos fazer nossas aplicações a serem seguras com autenticação e autorizaçao utilzando de forma gratuita o KeyCloak;

Espero que vocês tenham gostado de mais esse artigo, e que possam ajudar no dia a dia de vocês;

Segue o github desse exemplo:

GitHub - marraia/marraia.keycloak: Criação de webapi com a utilização do keycloak