Keycloak Setup#

In the section Docker With Keycloak, we have created a Keycloak server by docker. Now, we will continue to set up this Keycloak for OAuth2 using.

Realm#

What Is The Realm?#

Realm is a space in our Keycloak authorization server and by using this space, we can have our own users, roles and clients. Whatever we created in a particular Realm will be separated with other Realms.
Let's image that we are working in an enterprise applications and it will have many environments like DEV, TEST, UAT, STAGING and PRODUCTION. So we have to create many Realms for those environments and each Realm is a dedicated space for handling a specific environment or a specific application or a specific scenario.

Create A Realm#

To create a Realm, let's select the button as in the image below.

Then put a name for it and click button Create.

Then you can see your Realm is created.

Create Realm Roles#

Now, let's create some Roles for our Realm. So in Keycloak we have 3 roles;
- Realm Role
- Client Role
- Composite Role
There are no User Roles in Keycloak. You most likely confused that with User Role Mapping, which is basically mapping a role (realm, client, or composite) to the specific user.
In order to find out how these roles actually work, let's first take a look at a simple Realm model. As you can see in picture below, every Realm has one or multiple Clients and every Client can have multiple Users attached to it.

Role	Descriptions
Realm Role:	It is a global role, belonging to that specific realm. You can access it from any client and map to any user. Ex Role: 'Global Admin, Admin'
Client Role:	It is a role which belongs only to that specific client. You cannot access that role from a different client. You can only map it to the Users from that client. Ex Roles: 'Employee, Customer'
Composite Role:	It is a role that has one or more roles (realm or client ones) associated to it.

To create Realm Role, let's click on Realms roles and then click button Create role.

Then we put a role name and click save button.

Then you can see Realm roles have been created.

Client Credentials Grant Type#

In this example, we will try to setup the OpenID Connect for Client Credentials Grant Type on Keycloak server. Basically the OpenID Connect uses the same flow as the OAuth2 and it is just different about the scope that is sent to the authorization server.
If you have not know Client Credentials Grant Type or OAuth2 Flows, so you can read this topic OAUTH2 Flow.
Basically the Client Credentials Grant Type flow is described as the diagram below. We use this authentication flow only if there is no user and UI involved. Like 2 different applications want to share data between them using backend APIs.


sequenceDiagram

    Client->>Auth Server: 1. I want to access protected resources. Here <br/> are my client credentials. No user involved in this.
    Auth Server->>Client: 2. Hey Client, The credentials providided are <br/> correct. Here is the TOKEN to access the user <br/> resources.
    Client->>Resource Server: 3. Hey Resource Server, I want to access protected resources. <br/> Here is the token from the Authz Server
    Resource Server->>Client: 4. Hey Client. Your token is validated successfully. <br/> Here are the resources you requested.

Note: In Client Credentials Grant Type we should not return the refresh token following RFC6749 section 4.4.3.

Because authentication server have to take one more step for verifying the refresh token with using the same credentials which is used for getting the access token.

Create Client#

So, to create a Client in a Realm, let's follow steps as in the image below. We will select the Realm then click Clients and click button Create client.

Then in the General Setting, choose the Client Type as OpenID Connect and put a name for field Client ID and click Next button.

Now, at step Capability config, let's
- turn on Client authentication.
- uncheck Standard flow because it is used for Authorization Code Grant Type Flow
- uncheck Direct access grants because it is used for Resource Owner Password Credentials Grant.
- check Service accounts roles because it is used for Client Credentials Grant Type which is matched with this example.
- click button Save

Then you can see your Client as below.

Add Realm Roles#

Next, we will add Realm Roles into our client. You should choose Service accounts roles tab. Then click button Assign role.

Then select the Realm Roles that you want to add and click button Assign.

Testing#

So, Keycloak provide for us an api to get the information about our Realm and it called Discovery endpoint and the endpoint will have the pattern as below.

{{KEY_CLOAK_DOMAIN}}/auth/realms/{{REALM_ID}}/.well-known/openid-configuration

Example: 

http://localhost:8080/auth/realms/myrealm/.well-known/openid-configuration

We can try it with postman and you can see the result as below.

Now, with the information from the discovery endpoint, we will get the token_endpoint and use it with the client credentials from the created client in our Realm for getting the access_token.
The client_id can be got as the image below:

The client_secret can be got as the image below:

The grant_type should be hard code as client_credentials, because we are using Client Credentials Grant Type.
For the scope you should put it with value openId to let the Keycloak server know you are using OpenId Connect. You can also put any more value that you get from the field scopes_supported in the discovery endpoint response.
Now, let's use postman and try to call the token_endpoint, you will received an access_token and the id_token as in the image below.

Authorization Code Grant Type#

In this example, we will try to setup the OpenID Connect for Authorization Code Grant Type on Keycloak server. Basically the OpenID Connect uses the same flow as the OAuth2 and it is just different about the scope that is sent to the authorization server.
If you have not know Authorization Code Grant Type or OAuth2 Flows, so you can read this topic OAUTH2 Flow.
The Authorization Code Grant Type flow is described as the diagram below.


sequenceDiagram

    User->>Client: 1. I want to access my resources
    Client->>User: 2. Tell the Auth Server that you are fine to do this action.
    User->>Auth Server: 3. Hello Auth Server, please allowed the client to access my resources. <br/> Here is my credentials to prove my identity
    Auth Server->>Client: 4. Hey Client, user allowed you to access his <br/> resources. Here is AUTHORIZATION CODE.
    Client->>Auth Server: 5. Here is my client credentials, AUTHZ <br/> CODE. Please provide me a token.
    Auth Server->>Client: 6. Here is the token from Authorization Server
    Client->>Resource Server: 7. Hey Resource Server, I want to access the user resources. <br/> Here is the token from the Authz Server
    Resource Server->>Client: 8. Hey Client. Your token is validated successfully. <br/> Here are the resources you requested.

The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.

Create Client#

Like we created a client in a Realm before, let's follow steps as in the image below. We will select the Realm then click Clients and click button Create client.

Then in the General Setting, choose the Client Type as OpenID Connect and put a name for field Client ID and click Next button.

Now, at step Capability config, let's
- check Client authentication because it defines the type of the OIDC client. When it's ON, the OIDC type is set to confidential access type. When it's OFF, it is set to public access type
- check Standard flow because it is used for Authorization Code Grant Type Flow
- uncheck Direct access grants because it is used for Resource Owner Password Credentials Grant.
- click button Save

Then you can see your Client as below.

Create Realm User#

For Authorization Code Grant Type, we need to create a Realm User because Keycloak authorization server will require clients to prove their identity by giving username and password which are created in the Keycloak Realm users.
So, to create a user for our Realm, we should flow steps below.
We will select the Realm then click User and click button Add user.

Then we put a username, give some information and click button Create.

Next, when user is created then we continue to choose Credentials tab and click Set password and put the password as in the image below. We turn off field Temporary because we don't want the user have to change password at the first login.

Next, we will choose the Role mapping tab and click Assign role button to add the Realm role for this user.

Password Grant Type Flow#

In this example, we will try to setup the OpenID Connect for Authorization Code Grant Type on Keycloak server. Basically the OpenID Connect uses the same flow as the OAuth2 and it is just different about the scope that is sent to the authorization server.
If you have not know Password Grant Type Flow or OAuth2 Flows, so you can read this topic OAUTH2 Flow.
The Password Grant Type Flow flow is described as the diagram below.


sequenceDiagram

    User->>Client: 1. I want to access my resources
    Client->>Auth Server: 2. Hello Auth Server, User want to access <br/> his/her resources. Here are the credentials of <br/> the User
    Auth Server->>Client: 3. Hey Client, The credentials providided are <br/> correct. Here is the TOKEN to access the user <br/> resources.
    Client->>Resource Server: 4. Hey Resource Server, I want to access the user resources. <br/> Here is the token from the Authz Server
    Resource Server->>Client: 5. Hey Client. Your token is validated successfully. <br/> Here are the resources you requested.

We use this authentication flow only if the Client, Authorization Server and Resource Server are maintained by the same organization.
This flow will be usually followed by the enterprise applications who want to separate the Auth flow and business flow. Once the Auth flow is separated different applications in the same organization can leverage it.

Create Client#

Like we created a client in a Realm before, let's follow steps as in the image below. We will select the Realm then click Clients and click button Create client.

Then in the General Setting, choose the Client Type as OpenID Connect and put a name for field Client ID and click Next button.

Now, at step Capability config, let's
- Uncheck Standard flow because it is used for Authorization Code Grant Type Flow
- Check Direct access grants because it is used for Resource Owner Password Credentials Grant.
- click button Save

Then you can see your Client as below.

Create Realm User#

Like Authorization Code Grant Type, we need to create a Realm User because Keycloak authorization server will require clients to prove their identity by giving username and password which are created in the Keycloak Realm users.
So, to create a user for our Realm, we should flow steps below.
We will select the Realm then click User and click button Add user.

Then we put a username, give some information and click button Create.

Next, when user is created then we continue to choose Credentials tab and click Set password and put the password as in the image below. We turn off field Temporary because we don't want the user have to change password at the first login.

Next, we will choose the Role mapping tab and click Assign role button to add the Realm role for this user.

References#

RFC6749 section 4.4.3

Keycloak Setup#

Realm#

What Is The Realm?#

Create A Realm#

Create Realm Roles#

Client Credentials Grant Type#

Create Client#

Add Realm Roles#

Testing#

Authorization Code Grant Type#

Create Client#

Create Realm User#

Password Grant Type Flow#

Create Client#

Create Realm User#

See Also#

References#