Configuring an IAM solution
Recommended Keycloak setupโ
To build a minimal required Keycloak you have to configure the following items:
- a realm
- available roles - realm-level roles that can be assigned
- realm default roles - realm-level roles assigned to new users
- users
- import user roles
- clients
- role mappers
- service accounts
Recommended keycloak version: 18.0.x
Follow the next steps to build your Keycloak setup:โ
Creating a new realmโ
What are realms?
A realm is a space where you manage objects, including users, applications, roles, and groups. A user belongs to and logs into a realm. One Keycloak deployment can define, store, and manage as many realms as there is space for in the database.
To create a new realm, complete the following steps:
- Log in to the Keycloak Admin Console (go to the keylock admin URL corresponding to the selected environment, for example, let's say you use a QA or a development environment or a production).
- In the top left corner dropdown menu, click Add Realm.
If you are logged in to the master realm this dropdown menu lists all the realms created. The Add Realm page opens.
- You will be creating a brand-new realm from scratch, so type a realm name and click Create.
- Go to Realm Settings โ Tokens and set the following properties:
- SSO Session idle - suggested: 30 Minutes
- Access Token Lifespan - suggested: 30 Minutes
This is just an example, you can set any values you want for the token, and do not forget to check and apply properties suitable for your organization's needs.
Creating/importing user groups and rolesโ
You can either create or import a user group into a realm. We prepared a script that helps you to import a super admin group provided with the necessary default user roles.
- Run the Python script mentioned in the previous section.
- Add an admin user, for example,
admin@flowx.ai
user in the groupSUPER_ADMIN_USERS
(this group is added automatically if you use the script). - Add
ROLE_START_EXTERNAL
role in the Roles tab (this will be used later).
You can also validate if you were able to import all the roles by checking the following section:
ยปDefault rolesCreating new usersโ
To create a new user in the Flowx
realm as well as a temporary password for that account, complete the following steps:
- In the left menu bar click Users. The user list page opens.
- On the right side of the empty user list, click Add User. โMake sure you validate the user email by setting the Email Verified to ON.
- The only required field is
Username
. When you finish, click Save. The management page for your new user opens.
If the Username field is not visible (as you can see in the example above), please follow the next steps:
Right-click on the Add user page menu, then click inspect element.
Search for username (use Ctrl + F).
Delete the highlighted
ng-hide attribute
(fromform-group ng-hide
) and press Enter.The Username field will be available.
Save the user and go to Credentials.
Enter a password and set it not to be temporary.
Go to the Groups tab and then click join.
Adding clientsโ
What are clients?
Clients have trusted browser apps and web services in a realm. These clients can request Keycloak to authenticate a user. You can also define client-specific roles.
To add clients, complete the next steps:
- In the top left menu, click Clients then click Create.
- Use
{example}-authenticate
as client ID - it will be used for login/logout/refresh token by web and mobile apps. - Open the newly created client and edit the following properties:
- Set Access type to public (do not require a secret)
- Set Valid redirect URIs - define a valid URI pattern that a browser can redirect to after a successful login or logout
- Check Direct Access Grants Enabled and Implicit Flow Enabled to ON
- Add groups mapper to
{example}-authenticate
client - so the groups list will be added to the authorization token. For more information on how to add mappers to clients, check the following section.
Adding protocol mappersโ
What are protocol mappers?
Protocol mappers perform transformation on tokens and documents. They can do things like map used data into protocol claims, or just transform any requests going between the client and auth server.
There are multiple types of mappers that we will use in the following examples:
- Group Membership mapper - it can be used to map user groups to the authorization token
- User Attribute mapper - it can be used to map custom attributes, for example, mapping the businessFilters list to the token claim
- User Realm Role - it can be used to map a user realm role to a token claim
Group Membership mapperโ
To add a mapper, complete the next steps (example used: adding user groups in the authorization token):
- Go to clients โ your client โ mappers.
- Fill in a suggestive Name for the mapper.
- From the Mapper Type dropdown, choose Group Membership.
- In the Token Claim Name, insert the name of the claim that will be included in the token.
User Attribute mapperโ
Add customer business filters attribute to {example}-authenticate
client - so the business filters list will be added to the token claim.
You can find more information about business filters in the following section:
ยปBusiness filtersUser realm roleโ
Add roles mapper to {example}-authenticate
client - so roles will be available on the OAuth user info response.
Examplesโ
Loginโ
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin@flowx.ai' \
--data-urlencode 'password=password' \
--data-urlencode 'client_id= example-authenticate'
Refresh tokenโ
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id= example-authenticate' \
--data-urlencode 'refresh_token=ACCESS_TOKEN'
User infoโ
curl --location --request GET 'localhost:8080/realms/flowx/protocol/openid-connect/userinfo' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Authorizing clientโ
Add {example}-authorize
client - it will be used to authorize rest requests to microservices and Kafka
- set Access type as confidential
- check Standard Flow Enabled
Minimal auth config for microservicesโ
security:
type: oauth2
basic:
enabled: false
oauth2:
base-server-url: http://localhost:8080
realm: flowx
client:
access-token-uri: ${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token
client-id: example-authorize
client-secret: CLIENT_SECRET
resource:
user-info-uri: ${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/userinfo
Adding service accountsโ
What is a service account?
A service account is an account that allows a component to directly access the Keycloak API.
Admin service accountโ
This will be used by the admin microservice for making calls directly to the Keycloak API.
To add an admin service account, complete the next steps:
- Add a new client:
- set Access type as confidential
- check Service Accounts Enabled
- Go to Clients โ realm-management โ Roles and add the following service account client roles: manage-users.
- Add realm roles mapper to the newly created admin-service-account with the following properties:
- name: realm roles
- Mapper Type: User Realm Role
- Token Claim Name: roles
- Claim JSON Type: String
- Give it the necessary service account roles:
The admin service account defined in the example above can have the following assigned roles, based on the access scopes:
- manage-users
For more information, check the following section:
ยปConfiguring access rights for adminTask management service accountโ
This will be used by the task management microservice for making calls directly to keycloak API.
To add a task management service account:
- Add a new client:
- set Access type as confidential
- check Service Accounts Enabled
- Go to Clients โ realm-management โ Roles and add the following service account client roles under realm-management: view-users.
- Add role
ROLE_START_EXTERNAL
to it in service account roles โ realm roles.
- Add a realm-roles mapper:
- Add the necessary service accounts to it:
The task management service account defined in the example above can have the following assigned roles, based on the access scopes:
- manage-tasks
- manage-hooks
For more information, check the following section:
ยปConfiguring access rights for Task Management