Devprime | Documentation – Keycloak

Examples: Introduction

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

Keycloak is an identity management platform that supports application and microservices security in single sign-on processes with Identity, Access Management offering authentication and authorization integrated with the Devprime platform. This integration is done by the Security adapter.

Follow the steps below to prepare the local Keycloak environment with the basic settings to enable local integration testing with the security engine.

Initialize the Keycloak container using the command provided in the docker documentation.
Open the Keycloak url in http://localhost:8080 and view the Keycloak portal.
Log in by entering the user ‘admin’ and password ‘admin’.
Create a new Realm and set a name. In this example we will use ‘devprime’.

Configure some initial settings to allow user registration and use of email at login. To find this setting go to the Realm “Devprime” and locate the ‘Realm settings’ menu.

a) Locate the “Login” menu and enter the “Login screen customization” option and change it.

b) Locate the “Email settings” option and change it.

At this point we will create a “Client” to allow microservice access to Keycloak. In the main menu locate the “Clients” item and choose the “Create client” option.

Make an initial configuration by informing the “Client ID” and other settings according to General Settings and Capability config. In our example we use the name “myapp” for ClientID and change the Client authentication and Implicit flow.

First step of the setup

Second step of the setup

To allow url redirection between Keycloak and the microservice, it is necessary to register valid urls.

a) If you have the screen open from the previous step, locate the option “Access settings”
b) Add the url “https://localhost:5001/signin-oidc” in the Valid redirect URIs option.
c) This same screen is available in the main menu under “Clients” / “myapp”.

To obtain the microservice integration credentials with Keycloak go to the “Clients” menu and then enter “myapp” to locate the “Credentials” tab. Copy the secret key for use in your application.

This initial configuration will allow you to start the first tests on the security configuration in the microservices. Keycloak offers several options for authentication flows.

At the end, remember the parameters used and/or obtained in the configuration of the keycloak for use in the microservice. The Logout url below is an example returning the redirect to localhost

Another important option to configure is “Valid redirect URIs” which defines the authorized urls. In our scenario we are using localhost in the local environment. You must register all urls or you can use the example “https://localhost:5001/*”.

Item	Parameter
Domain	https://localhost:8080/auth/realms/devprime
ClientID	Your 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

Common Error:

Verify the ClientID name and credential

[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'."]

Next steps:

Examples: Applying Web Security

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

During this scenario we will use the Devprime stack security adapter to enable the security settings so that when there is an access request the user is required to authenticate in a centralized Keycloak database.

To move forward in this scenario, it is essential to have an instance of Keycloak and follow the steps as instructed below:

Create an instance of Keycloak following the steps indicated.
Install the Devprime CLI.
Creating a microservice for use in the “ms-sec-order” demo
dp new ms-order --state mongodb --stream rabbitmq --marketplace order --init
After completion, you can run the microservice. Then finish.
.\run.ps1 or ./run.sh (Linux, macOS)
Adding Web template for use in the demo. This will create some web pages
to use in the demonstration.
dp add web login

After running we will have a new Endpoint called “/private” that already brings the “Authorize” attribute necessary to indicate that that url requires authentication. The excerpt from the file below “code src/App/appsettings.json” demonstrates this scenario
with the /private, /login, and /logout urls.

To view by 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);
        });
    }

Open the settings file and include in the security adapter the Keycloak parameters obtained in item 1 of this step-by-step by changing the items “ClientID / ClientSecret / LogoutUri / Audience”

IMPORTANTE:
Put the same value of the ClientID in the Audience field as shown in the example below and make sure
that EnableOIDC is set to “true”.

Procedure to include OIDC security configuration:

a) Open through Visual Studio Code
code src/App/appsettings.json

b) Copy the code below and put it in the 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"
    }
  },

Run the application and open https://localhost:5001 to view the new links added.
Access the private link and you will be directed to authentication
Log in or register on Keycloak under “Register”.
In case of success, the private web page will be released.

Next steps:

You have secured a web application using Keycloak and a microservice using the Devprime platform. Congratulations🚀🚀🚀

Examples: Applying security to API's

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

During this scenario we will use the Devprime stack security adapter to enable the security settings and we recommend that you have implemented the item Applying Web Security.

To move forward in this scenario, it is essential to have an instance of Keycloak and follow the steps as instructed below:

Create an instance of Keycloak following the steps indicated.
Install the Devprime CLI.
Creating a microservice for use in the “ms-sec-order” demo
dp new ms-order-payment --state mongodb --stream rabbitmq --marketplace payment --init

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

After completion, you can run the microservice. Then finish.
.\run.ps1 or ./run.sh (Linux, macOS)
Changing the default microservice port
We will now edit the appsettings.json file available in the ms-payment/src/App folder to configure the web adapter and then the security adapter. Gate the value of the url parameter to avoid port conflict.

  "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"
  },

Open the settings file and include in the security adapter the Keycloak parameters obtained in item 1 of this step-by-step by changing the items “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"
    }

After completing this stage, the API access security control is already configured. Locate the Payment.cs file in the ms-payment/src/Adapters/Web/ folder to configure the restriction of access to a route in the API. In the example below we will apply to the 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))));
    }

Re-run the microservice and open the url https://localhost:5003
Enter the swagger and try to perform a “GET”
Since security is active, the response will be a 401 indicating lack of permission
You can also perform the same test using the 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

Next steps:

You’ve secured access to a microservice API by using Keycloak.
Congratulations🚀

Examples: Using curl to access protected API

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

Create an instance of Keycloak following the steps indicated.
Run the payment.
Make sure you have registered a user in Keycloak and obtained Realm credentials.
To obtain the authentication token through curl, it is necessary to make a post in the Keycloak API informing the parameters: username, password, client_id, client_secret.

a) After obtaining the parameters

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) After executing, you should get the result as shown in the example below.

{"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"}

In this example we have reduced the size of the result Access Token to make it easier to see. There are a few tools that allow you to view the JSON Web Token if you want to view the Keycloak result.

c) Get the value of the access token and assemble the query to perform a GET in the protected API entering the parameter “Authorization: Bearer” in the Header.

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) The same example can be repeated to perform a POST in the protected API.

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\"}'