Devprime | Documentação – Keycloak

Examples: Introdução

Mon, 01 Jan 0001 00:00:00 +0000

O Keycloak é uma plataforma para gestão de identidade com suporte a segurança em aplicativos e microsserviços em processos de single sign-on with Identity, Access Management oferecendo autenticação e autorização integrados a plataforma Devprime. Essa integração é feita pelo adapter de Security.

Siga os passos abaixo para preparar o ambiente local do Keycloak com as cofigurações básicas para habilitar os testes de integração local com o mecanismo de segurança.

Inicialize o container do Keycloak utilizando o comando disponibilizado na documentação do Docker.
Abra a url do Keycloak em http://localhost:8080 e visualize o portal do Keycloak.
Efetue o login informando o usuário ‘admin’ e senha ‘admin’.
Crie um novo Realm e defina um nome. Neste exemplo utilizaremos ‘devprime’.

Defina algumas configurações iniciais para permitir o cadastro de usuário e utilização do email no login. Para encontra essa configuração vá ao Realm “Devprime” e localize o menu ‘Realm settings’.

a) Localize o menu “Login” e entre na opção “Login screen customization” e altere.

b) Localize a opção “Email settings” e altere.

Nesse momento nós criaremos um “Client” para permitir acesso do microsserviço ao Keycloak. No menu principal localize a o item “Clients” e escolha a opção “Create client”.

Efetue uma configuração inicial informando o “Client ID” e demais configurações conforme General Settings e Capability config. Em nosso exemplo utilizamos o nome “myapp” para ClientID e alteraremos o Client authentication e Implicit flow.

Primeiro passo da configuração

Segundo passo da configuração

Para permitir o redicionamento de url entre o Keycloak e o microsserviço é necessário cadastrar urls validas.

a) Se estiver com a tela aberta do passo anterior localize a opção “Access settings”
b) Adicione a url “https://localhost:5001/signin-oidc” na opção Valid redirect URIs.
c) Essa mesma tela está disponivel no menu principal em “Clients” / “myapp”.

Para obter as credenciais de integração do microsserviço com o Keycloak vá ao menu “Clients” e depois entre em “myapp” para localizar a aba “Credentials”. Copie a chave secret para uso na sua aplicação.

Essa configuração inicial irá permitir iniciar os primeiros testes na confguração de seguraça no microsserviços. O Keycloak oferece diversas opções de fluxos de autenticação.

Ao final lembre das parâmetros utilizados e/ou obtidos na configuração do keycloak para utilização no microsserviço. O Logout url abaixo é um exemplo retornando o redirect para localhost

Uma outra opção importante a ser configurada é “Valid redirect URIs” que define as url autorizadas. Em nosso cenário estamos utilizando o localhost no ambiente local. Você deve cadastrar todas urls ou pode utilizar o exemplo “https://localhost:5001/*”.

Item	Parâmetro
Domain	https://localhost:8080/auth/realms/devprime
ClientID	Seu ClientID
ClientSecret	Your Secrets
LogoutUri	https://localhost:8080/auth/realms/devprime/protocol/openid-connect/logout?redirect_uri=https%3A%2F%2Flocalhost%3A5001
Valid redirect URIs	https://localhost:5001/signin-oidc

Erro comun:

Verificar o nome do ClientID e a credencial

[ERR][Web]["HTTP"][System.Exception]["Microsoft.AspNetCore.Authentication"]
["An error was encountered while handling the remote login." "An error was encountered while handling the remote login.
Message contains error: 'unauthorized_client', error_description: 'Invalid client or Invalid client credentials', error_uri: 'error_uri is null'."]

Próximos passos:

Examples: Aplicando segurança na Web

Mon, 01 Jan 0001 00:00:00 +0000

Durante esse cenário nós utilizaremos o adapter de security do Devprime stack para ativar as configurações de segurança para quando houver uma solicitação de acesso ser requerido a autenticação do usuário em uma base centralizada do Keycloak.

Para avançar nesse cenário é fundamental ter uma instância do Keycloak e seguir os passos conforme instruções abaixo:

Crie uma instância do Keycloak seguindo os procimentos indicados.
Instale o Devprime CLI.
Criando um microservico para uso na demonstração “ms-sec-order”
dp new ms-order --state mongodb --stream rabbitmq --marketplace order --init
Após a conclusão é possivel executar o microsserviço. Depois finalize.
.\run.ps1 ou ./run.sh (Linux, macOS)
Adicionando template Web para utilização na demonstração. Esse procedimento criará algumas páginas web
para utilizarmos na demonstração.
dp add web login

Após executar teremos um novo Endpoint chamado “/private” que já traz o atributo “Authorize” necessário para indicar que aquela url requer uma autenticação. O trecho do arquivo abaixo “code src/App/appsettings.json” demontra esse cenário
com as urls /private, /login e /logout.

Para visualizar pelo Visual Studio Code:
code src/App/appsettings.json

    public override void Endpoints(WebApplication app)
    {
        app.MapGet("/private", [Authorize]
        (ClaimsPrincipal user) =>
        {
            StringBuilder sb = new StringBuilder();
            foreach (var claim in user.Claims)
            {
                sb.Append($"{claim.Type}={claim.Value}{System.Environment.NewLine}");
            }
            return sb.ToString();
        });
        app.MapGet("/login", async (HttpContext http, string returnUrl) =>
        {
            if (string.IsNullOrWhiteSpace(returnUrl))
                returnUrl = "/";
            await http.ChallengeAsync(SecurityConfig.Identity.AuthenticationScheme, new AuthenticationProperties()
            {RedirectUri = returnUrl});
        });
        app.MapGet("/logout", [Authorize]
        async (HttpContext http) =>
        {
            await http.SignOutAsync(SecurityConfig.Identity.AuthenticationScheme, new AuthenticationProperties{RedirectUri = "/"});
            await http.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        });
    }

Abra o arquivo de configurações e inclua no adapter de security os parametros do Keycloak obitidos no item 1 desse passo a passo alterando os itens “ClientID / ClientSecret / LogoutUri / Audience”

IMPORTANTE:
Coloque o mesmo valor do ClientID no campo Audience conforme exemplo abaixo e certifique
que o EnableOIDC está como “true”.

Procedimento para incluir configuração de segurança por OIDC:

a) Abra pelo Visual Studio Code
code src/App/appsettings.json

b) Copie o código abaixo e coloque no appsettings.json

  "Devprime_Security": {
    "Enable": "true",
    "Identity": {
      "Enable": "true",
      "Type": "keycloak",
      "Domain": "http://localhost:8080/realms/devprime",
      "ClientId": "myapp",
      "ClientSecret": "your-clien-secret",
      "EnableOIDC": "true",
      "AuthenticationScheme": "OpenIdConnect",
      "Audience":"myapp",
      "LogoutUri": "http://localhost:8080/auth/realms/devprime/protocol/openid-connect/logout?redirect_uri=https%3A%2F%2Flocalhost%3A5001",
      "Scopes": "openid;email"
    }
  },

Execute a aplicação e abra https://localhost:5001 para visualizar os novos links adicionados.
Acesse o link private e será direcionado para a autenticação
Efetue o login ou cadastre-se no Keycloak em “Register”.
Em caso de sucesso a página Web privada será liberada.

Próximos passos:

Você protegeu uma aplicação web utilizando o Keycloak e um microsserviço utilizando a plataforma Devprime. Parabéns🚀🚀🚀

Examples: Aplicando segurança nas API's

Mon, 01 Jan 0001 00:00:00 +0000

Durante esse cenário nós utilizaremos o adapter de security do Devprime stack para ativar as configurações de segurança e nós recomendamos que tenha implementado o item Aplicando segurança na Web.

Para avançar nesse cenário é fundamental ter uma instância do Keycloak e seguir os passos conforme instruções abaixo:

Crie uma instância do Keycloak seguindo os procimentos indicados.
Instale o Devprime CLI.
Criando um microservico para uso na demonstração “ms-sec-order”
dp new ms-order-payment --state mongodb --stream rabbitmq --marketplace payment --init

dp new ms-order-delivery –state mongodb –stream rabbitmq –marketplace delivery –init

Após a conclusão é possivel executar o microsserviço. Depois finalize.
.\run.ps1 ou ./run.sh (Linux, macOS)
Alterando a porta padrão do microsserviço
Nós vamos agora editar o arquivo appsettings.json disponível na pasta ms-payment/src/App para configurar o adapter web e depois o adapter security. Aletre o valor do parâmetro url para evitar conflito de portas.

  "Devprime_Web": {
    "url": "https://localhost:5003;http://localhost:5002",
    "enable": "true",
    "enableswagger": "true",
    "PostSuccess": "201",
    "PostFailure": "500",
    "GetSuccess": "200",
    "GetFailure": "500",
    "PatchSuccess": "200",
    "PatchFailure": "500",
    "PutSuccess": "200",
    "PutFailure": "500",
    "DeleteSuccess": "200",
    "DeleteFailure": "500",
    "EnableWebLegacy": "false",
    "EnableStaticFiles": "true",
    "ShowHttpRequests": "false"
  },

Abra o arquivo de configurações e inclua no adapter de security os parametros do Keycloak obitidos no item 1 desse passo a passo alterando os itens “Domain, ClientID / ClientSecret / LogoutUri / Audience”
code ./src/App/appsettings.json

  "Devprime_Security": {
    "Enable": "true",
    "Identity": {
      "Enable": "true",
      "Type": "keycloak",
      "Domain": "http://localhost:8080/realms/devprime",
      "ClientId": "Your-app-name",
      "ClientSecret": "Your-secret",
      "EnableOIDC": "false",
      "Audience":"Your-app-name",
      "AuthenticationScheme": "OpenIdConnect",
      "LogoutUri": "http://localhost:8080/auth/realms/devprime/protocol/
      openid-connect/logout?redirect_uri=https%3A%2F%2Flocalhost%3A5001",
      "Scopes": "openid;email"
    }

Após concluindo esse estágio o controle de segurança de acesso a API já configurado. Localize o arquivo Payment.cs na pasta ms-payment/src/Adapters/Web/ para configurar a restrição de acesso à uma rota na API. No exemplo abaixo aplicaremos no item “app.MapPost /v1/payment”.

    public override void Endpoints(WebApplication app)
    {
        //Automatically returns 404 when no result  
        app.MapGet("/v1/payment" ,[Authorize] async (HttpContext http, IPaymentService Service, int? limit, int? offset, string ordering, string ascdesc, string filter) => await Dp(http).Pipeline(() => Service.GetAll(new Application.Services.Payment.Model.Payment(limit, offset, ordering, ascdesc, filter)), 404));
        //Automatically returns 404 when no result 
        app.MapGet("/v1/payment/{id}", async (HttpContext http, IPaymentService Service, Guid id) => await Dp(http).Pipeline(() => Service.Get(new Application.Services.Payment.Model.Payment(id)), 404));
        app.MapPost("/v1/payment", async (HttpContext http, IPaymentService Service, Devprime.Web.Models.Payment.Payment command) => await Dp(http).Pipeline(() => Service.Add(command.ToApplication())));
        app.MapPut("/v1/payment", async (HttpContext http, IPaymentService Service, Application.Services.Payment.Model.Payment command) => await Dp(http).Pipeline(() => Service.Update(command)));
        app.MapDelete("/v1/payment/{id}", async (HttpContext http, IPaymentService Service, Guid id) => await Dp(http).Pipeline(() => Service.Delete(new Application.Services.Payment.Model.Payment(id))));
    }

Execute novamente o microsserviço e abra a url https://localhost:5003
Entre no swagger e tente efetuar um “GET”
Como a segurança está ativa a resposta será um 401 indicando falta de permissão
Você também pode realizar o mesmo teste utilizando o curl
curl https://localhost:5003/v1/payment -i

HTTP/1.1 401 Unauthorized
Content-Length: 0
Date: Fri, 20 Jan 2023 23:49:26 GMT
Server: Kestrel
WWW-Authenticate: Bearer

Próximos passos:

Você protegeu o acesso a uma API do microsserviço utilizando o Keycloak.
Parabéns🚀

Examples: Utilizando curl para acessar API protegida

Mon, 01 Jan 0001 00:00:00 +0000

Crie uma instância do Keycloak seguindo os procimentos indicados.
Execute o microsserviço payment.
Certifique de ter cadastrado um usuário no Keycloak e otido as credenciais do Realm.
Para obter o token de autenticação pelo curl é necessário realizar um post na API do Keycloak informando os parâmetros: username, password, client_id, client_secret.

a) Após obter os parâmetros

curl -X POST http://localhost:8080/realms/devprime/protocol/openid-connect/token -H 'Content-Type: application/x-www-form-urlencoded' -d username=$username -d password=$password -d grant_type=password -d client_id=$client -d client_secret=<secret> --insecure

b) Após executar deve obter o resultado conforme o exemplo abaixo.

{"access_token":"eyJhbGciOiJSUzI1NDdfOE1DdTVvSU5OR1pyN3BIeV9jIn0","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyn0.g3GJR-jdc0TpsL9E","token_type":"Bearer","not-before-policy":0,"session_state":"21d413e9-cffa-47227bec6","scope":"profile email"}

Nesse exemplo nós reduzimos o tamanho do result Access Token para facilitar a visualização. Exite algumas ferramentas que permitem visualizar o JSON Web Token caso deseje inspesionar o resultado do Keycloak.

c) Obtenha o valor do access token e monte a consulta para efetuar um GET na API protegida informando no Header o parâmetro “Authorization: Bearer”.

1
2

curl -X GET https://localhost:5003/v1/payment -H "Authorization: Bearer eyJhbGciOiJSUzI1NDdfOE1DdTVvSU5OR1pyN3BIeV9jIn0" -H 'accept: */*'
grant_type=password -d client_id=$client -d client_secret=<secret> --insecure

d) O mesmo exemplo pode ser repetido para efetuar um POST na API protegida.

curl -X 'POST' 'https://localhost:5003/v1/payment' -H "Accept:application/json"  -H "Content-Type:application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NDdfOE1DdTVvSU5OR1pyN3BIeV9jIn0" -d '{\"customerName\": \"Ramon\", \"orderID\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"value\": \"0\"}'