Chapter 10: Managing Users

In the previous chapters, you learned how to deploy, run, and use Keycloak to authenticate and authorize users in your applications. You also learned how to manage users in Keycloak to run some of the examples in this book.

In this chapter, we are going to take a closer look at the capabilities provided by Keycloak that are related to identity management and federation, such as how users are created and managed, how users can manage their own accounts, how to manage credentials, and how to integrate with different identity stores and identity providers to authenticate users and fetch their information through open protocols such as OpenID Connect, Security Assertion Markup Language (SAML), and Lightweight Directory Access Protocol (LDAP).

In this chapter, we will cover the following topics:

  • Managing local users
  • Integrating with LDAP and Active Directory
  • Integrating with social identity providers
  • Integrating with third-party identity providers
  • Allowing users to manage their data

By the end of this chapter, you will be able to leverage these capabilities to effectively manage your users, as well as understand how they can be used to solve common problems related to identity management and federation.

Technical requirements

Check out the following link to see the Code in Action video:

https://bit.ly/3vIOf4i

Managing local users

In the previous chapters, you had to create users in Keycloak to run some of the examples provided in this book. In this section, we are going to deep dive into some key capabilities provided by Keycloak to manage your users once they are stored in Keycloak's internal database. For now on, whenever you read about a local user, you will think about a user stored in a Keycloak database.

As an identity management solution, Keycloak gives you several capabilities to manage user identities. In this section, we will look at the following topics:

  • How to create users
  • How to manage user credentials
  • How to obtain and validate user information
  • How to enable user self-registration
  • How to extend user information using attributes

In the next section, we are going to start our journey by looking at how to create a local user in Keycloak.

Creating a local user

To create a new user in Keycloak, click on the Users link on the left-hand side panel. Once you've done that, you will be presented with a list showing all the users that are available in the realm. At the top right of that list, you have an Add user button. By clicking on this button, you will be presented with the user creation page.

When creating a new user, you are only asked for a few pieces of information. In fact, you should be able to create a new user by providing only a username. Let's create a user whose username is set to alice:

Figure 10.1 – Creating a new user

Figure 10.1 – Creating a new user

Click on Save to create the user.

Creating a user is a trivial task. Keycloak depends on a few pieces of basic information about users while still allowing you to decorate them with additional information, as we will see later. This basic set of information is what Keycloak needs to identify a user, to correlate the user with other functionalities, and to issue tokens after authenticating users.

Note

When you create a new user, that user belongs to the realm you are managing. Users created in a realm can only authenticate through the realm they belong to.

Creating a user using the administration console is useful when the administrator has all the information about a user beforehand. However, depending on the use case, that is not always the case, so you may want to either allow your users to self-register in your realm or ask them for their information as part of the authentication process.

In this section, you learned about how to create a user in Keycloak. You also learned that Keycloak depends on a few pieces of information about users so that they can authenticate in a realm. You also learned that Keycloak allows you to decorate your users with additional information and that once they are created, they can only authenticate through the realm they belong to.

In the next section, we will look at how to manage user credentials.

Managing user credentials

After creating users, they should be able to authenticate in the realm. For that, we need to set up credentials for the user. Keycloak supports different forms of authentication using different types of credentials. As we will see in Chapter 11, Authenticating Users, users can authenticate in different ways, such as by using passwords, one-time keys, security devices, X.509 certificates, and so forth.

To manage user credentials, click on the Credentials tab after selecting a user from the users list. In this tab, you should be able to see all the credentials associated with a user, as well as perform specific actions such as delete or modify credentials. You will also be provided with shortcuts to easily set a password (the simplest form of authentication, although not the strongest) for a user.

Note

Keycloak does not expose sensitive data associated with credentials, only the basic and non-sensitive data associated with them. Depending on your security requirements, you may also want to encrypt data at rest in the database.

We are going to look at other types of credentials in the next chapter, but for now, let's create a password for the alice user that we just created. For that, fill in the Password and Password Confirmation fields with any password you want, and turn off the Temporary setting. Do not worry about this setting for now as we are going to talk about it in the next chapter. Just keep in mind that by disabling it, we are creating a definitive password for the user. Click on the Set Password button to set the user's password:

Figure 10.2 – Setting a new password for a user

Figure 10.2 – Setting a new password for a user

After setting the password, you will see that the list of credentials has been updated with the new password we just set for the user. From that list, you can view information about any credential associated with a user – non-sensitive information – as well as delete it.

Now, let's test whether the user can authenticate in our realm. For that, we are going to try to access the account console, an application provided by Keycloak where users can manage their own information. We are going to discuss it in the following sections, but for now, just open your browser at http://localhost:8080/auth/realms/myrealm/account. You should be redirected to the myrealm login page.

Type in the username and password for the user alice and click on the Login button. If everything is working properly, you should be able to access the account console as the user alice:

Figure 10.3 – Authenticating as the newly created user

Figure 10.3 – Authenticating as the newly created user

In this section, you learned how to manage user credentials through the administration console. You also learned that Keycloak allows you to manage different types of credentials, with shortcuts for managing the user password. You also learned that, once created, all the credentials associated with a user – not only passwords – can be managed through the Credentials tab.

In the next section, we are going to look at how to interact with users during the authentication process to gather more information about them.

Obtaining and validating user information

In the previous sections, we created the user alice by providing only a username. We also set a password for this user to authenticate in the realm. As you may have noticed, we are missing some important information about alice, and we want her to fill in that information to create her account.

Keycloak allows you to interact with users during the authentication process using a functionality called Required User Actions. This setting is related to the actions that the user should perform prior to authenticating to a realm. Keycloak provides a good set of common actions covering different scenarios, such as the following:

  • Verify Email: Send an email to the user – if one was set – to confirm it belongs to that user.
  • Update Password: Ask the user to update their password.
  • Update Profile: Ask the user to update their profile by providing their first name, last name, and email.

There are other options, but the preceding actions should give you an idea of how powerful this setting is and how you can interact with your users when they are authenticating.

Let's configure the Update Profile action for alice and obtain the information we are missing about her account. For that, select alice from the users list and select Update Profile from the list of available actions in the Required User Actions field. Then, click on the Save button:

Figure 10.4 – Forcing users to update their profile while logging in to update 
missing account information

Figure 10.4 – Forcing users to update their profile while logging in to update missing account information

Now, let's try to access the account console as alice. For that, open your browser at http://localhost:8080/auth/realms/myrealm/account. You should now be redirected to the myrealm login page.

Type in the username and password for alice and click on the Login button. If everything is working properly, you should be redirected to a page asking for the information we are missing from that user. Fill in all the fields and click on the Submit button:

Figure 10.5 – Asking a user to update their account information

Figure 10.5 – Asking a user to update their account information

Once you submit the information, Keycloak is going to update the user with the information provided. The updated information should now be available when you access the account console.

The same idea applies to any other required action you set for a user, where each is related to specific steps that the user is required to complete before authenticating to a realm. For instance, if you set the Update Password action, the user is going to be asked to reset their password, whereas the Verify Email action is going to make sure the email associated with the user is valid through an email verification process.

In this section, you learned how Keycloak allows you, as an administrator, to interact with your users to obtain and validate information about their accounts.

In the next section, we are going to look at how to allow users to self-register their accounts.

Enabling self-registration

Depending on your requirements, you might want to allow users to self-register in a realm and delegate them the responsibility of filling in their information. Compared to manually creating a user, Keycloak is going to provide a link on the login page for user self-registration.

For that, click on Realm Settings in the left-hand side menu and then click on the Login tab. In this tab, enable the User registration option.

Now, let's create a new user by going through the self-registration process. Open your browser at http://localhost:8080/auth/realms/myrealm/account. At the login page, click on the Register link:

Figure 10.6 – Allowing users to sign up to a realm

Figure 10.6 – Allowing users to sign up to a realm

Once you've done that, you should be presented with a registration page, asking you to provide the same information that you did when you created users through the administration console. Fill in the fields with any information you want and click on the Register button to create the new user.

Now, go back to the Keycloak administration console and check whether the user you just created is shown in the users list. If everything is correct, you should be able to see the user you just created in that list.

Self-registration is a powerful feature and a must-have for certain use cases where users should be allowed to sign up to a realm. It also provides the necessary level of flexibility so that you can customize the registration page to obtain additional information about users, such as their mobile number or address, according to your needs. We are going to talk about customization in Chapter 13, Extending Keycloak.

In this section, you learned how to enable self-registration for a realm so that users can create their own account in a realm without any intervention from an administrator.

In the next section, we will look at how to manage additional information about users.

Managing user attributes

Keycloak allows you to manage additional metadata about users using attributes. As you learned in the previous sections, Keycloak relies on a basic set of information to identify and authenticate users. This information is also made available when you're introspecting tokens or accessing a user's profile. To manage the attributes of a user, select the respective user from the users list and click on the Attributes tab. Each attribute has a key – the name of the attribute – and a text value.

User attributes can solve different types of problems, from passing additional information about users to applications, to enabling different forms of authorization, such as Attribute-Based Access Control (ABAC).

When using attributes, you are probably going to need to create protocol mappers so that they can be mapped to tokens to make them available to applications, or even when querying the introspection token and userinfo endpoints.

When extending Keycloak, as we are going to see in Chapter 13, Extending Keycloak, you should also be able to extend the account console to populate user accounts with additional information using attributes. The same goes for customizing the update profile page, which is shown to users during the authentication process, as we learned in the previous sections. Here, you can store custom information that was gathered during this step using attributes.

In this section, you learned how to extend Keycloak's user model by using user attributes. You also learned that by leveraging user attributes, you can extend different parts of Keycloak to obtain additional information from users and store it as user attributes. You also learned that user attributes are commonly used to pass additional information about users to applications using protocol mappers.

In the upcoming sections, we are going to look at how to integrate with third-party identity providers and identity stores to manage users from sources other than a Keycloak database. We will start by learning how to fetch user information from LDAP directories.

Integrating with LDAP and Active Directory

Many organizations still use an LDAP directory as their single source of truth for digital identities. Keycloak allows you to integrate with different LDAP server implementations so that you can leverage your existing security infrastructure and use all the authentication and authorization capabilities provided by Keycloak.

Keycloak can integrate using LDAP in different ways; it can act as a stateful broker where data from your LDAP directory is imported into the Keycloak database, as well as kept in sync with your LDAP directory, or it can act as a stateless broker delegating credential verification to your LDAP directory. You should also be able to set up multiple LDAP directories within a single realm and configure a priority order that Keycloak should respect when authenticating users.

In Keycloak, the term "user federation" refers to the capability of integrating with external identity stores. LDAP is a form of user federation and, as such, can be configured by clicking on the User Federation link on the left-hand side menu of the administration console.

To configure a new LDAP server, select ldap from the list of available providers:

Figure 10.7 – Creating a new LDAP user federation provider

Figure 10.7 – Creating a new LDAP user federation provider

After selecting the provider, you will be presented with a page containing all the settings you'll need to integrate with an LDAP directory. Keycloak supports the most common LDAP vendors, including Active Directory. The Vendor field allows you to choose one of these vendors and Keycloak does its best to find the best default setting for the vendor you choose.

If you are interested in integrating Keycloak using LDAP, you should become familiar with most of the settings on this page, mainly those related to connection settings and the structure of the LDAP directory. Here, we will focus on the additional settings provided by Keycloak to customize the integration, starting with the Import Users setting.

The Import Users setting allows you to define whether Keycloak should import data from your LDAP server into the database. By default, this setting is enabled so that whenever users authenticate through an LDAP provider, the information about that user is persisted into the database. One of the main reasons this setting is enabled by default is that if it wasn't, you wouldn't be able to leverage all of Keycloak's capabilities – you would only be able to use it as a broker to authenticate your users using the LDAP directory.

Basically, when a user tries to authenticate, Keycloak will check whether the user is available from its database. If no user is found, Keycloak will try to look up the user in your LDAP directory. If the user trying to authenticate is there, Keycloak will authenticate the user using the LDAP protocol and, if successful, import the user into the database. Once imported, the user is considered a federated user and a link is created between the user and the LDAP provider.

This link between the user and the LDAP provider is a key aspect of user federation. By looking at the link the user has to a specific user federation provider, such as LDAP, Keycloak is able to differentiate whether a user is a local user or a federated user. In this context, the term "federated" refers to the trust that's created between Keycloak and an external identity store – in this case, the LDAP directory – so that both can share identity and access management data.

Keycloak provides some key synchronization settings for managing how data is read and written back to an LDAP directory. Before you do anything else, you should decide which synchronization strategy you want through the Edit Mode setting. You can choose from three different strategies: READ_ONLY, WRITABLE, and UNSYNCED.

The READ_ONLY strategy allows you to use your LDAP directory in read-only mode, where changes to federated users are not replicated back to the LDAP directory. On the other hand, the WRITABLE strategy is a powerful strategy that allows you to replicate any change that's made to federated users back to the LDAP directory.

Whether you should use a read-only or writable strategy depends on your use case. Under some circumstances, LDAP is the single source of truth for identities in the organization that you do not have much control over. If you are using Keycloak to modernize your security infrastructure while still centralizing identity management in your LDAP directory, then the READ_ONLY strategy makes sense.

However, if you have plans to migrate from LDAP and want to centralize identity management through Keycloak, then the writable strategy should help you during that journey. It should also allow you to keep your LDAP active and in sync with the changes that are made through Keycloak.

Once you've decided which strategy works best for you, you can look at additional settings provided by Keycloak to control how synchronization should happen. Keycloak allows you to synchronize user information by manually triggering the synchronization process through the administration console, or by scheduling a time when synchronization should happen automatically.

To trigger a manual synchronization for user information, you should click on the Synchronize All Users button, which becomes available once you've created your LDAP provider. In fact, it is a good practice to run a full synchronization right after creating your provider. The reason for this is that this step is going to help you avoid importing users when they authenticate for the very first time. You are also provided other actions to perform, including synchronizing local users that have changed after the last synchronization, removing users that have been imported from the LDAP provider, and removing the link between users and an LDAP provider, effectively changing the user to a regular local user.

Once your users have been imported, you can schedule periodic synchronization according to your needs. Synchronization can be scheduled for a full or partial sync.

A full sync means that Keycloak is going to check the LDAP tree for changes that need to be replicated to the database, so that new users that are created in LDAP, as well as updated information about those users, are kept in sync.

A partial sync means that Keycloak is going to look up new users and make changes to existing users after the last synchronization happened, hence helping keep Keycloak updated using a more efficient strategy.

In this section, you learned about user federation and how Keycloak can integrate with existing LDAP servers to authenticate users and synchronize information.

In the next section, you will learn about LDAP mappers and their importance in terms of fetching additional information from an LDAP directory, as well as the behavior of the integration.

Understanding LDAP mappers

Just like users, Keycloak can also fetch other types of information from LDAP. Different to how you fetch users from LDAP – which is part of the core functionality of an LDAP provider – this information is fetched using mappers.

An LDAP mapper is a special, and powerful, functionality in Keycloak for mapping information from LDAP into Keycloak and vice versa. It provides another extension point to LDAP's integration and fine-grained control over how to read and write LDAP data for users, groups, roles, certificates, or even information that is only available when you're using a specific LDAP vendor, such as Active Directory. Whenever you need to map a specific set of data from LDAP, you should go through the list of supported mappers and find one that suits your needs.

When creating a new provider, Keycloak automatically configures a set of mappers, depending on the configuration of the provider. For instance, depending on the import mode or the edit mode, a different set of mappers is created. That is why deciding on these two settings is important prior to creating the provider. Otherwise, you would need to change mappers accordingly when changing these settings once a provider has been created.

To manage the mappers associated with an LDAP provider, click on the Mappers tab of the provider you are managing. On this tab, you are presented with a list of all the mappers that are currently active for the provider. From this page, you can also associate new mappers with your provider. You can do this by clicking on the Create button in the top-right corner of the list.

There are several types of mappers that you can use, with each being specific to a particular task. In the next few sections, we are going to look at how to create mappers to manage group and role data from LDAP.

Synchronizing groups

To manage group data from LDAP, click on the Create button in the top-right corner of the mappers list.

Type in a name for the new mapper and select group-ldap-mapper from the Mapper Type field.

Some of the settings on this page are specific to how groups are organized in the LDAP tree. For instance, you must provide the Distinguished Name (DN) of where your groups are located, the attribute that will be used to fetch the group name, as well as how membership information is defined in your LDAP tree so that Keycloak can automatically discover the groups that users belong to.

The group-ldap-mapper type gives you several settings to configure how groups should be fetched from LDAP and how data synchronization should work. Some of the settings are specific to how groups are organized in the LDAP tree.

The first step when creating this mapper is to set the location of the groups in your LDAP tree. For that, you should fill in the LDAP Groups DN field with the base DN where all your groups are located. You should also be able to provide an additional filter if you have a more complex LDAP tree, where groups should be fetched based on some criteria. For that, you can set a filter using the LDAP Filter field.

Keycloak is going to look up group entries from the base DN based on the object classes you've defined for group entries. You can set the object classes using the Group Object Classes field.

The next step is to configure how Keycloak should map information from group entries to Keycloak.

The name of a group can be mapped from these entries using the Group Name LDAP Attribute field. You can change this field to whatever LDAP attribute you are using to store the group's name. Usually, the Common Name (CN) attribute is used for this purpose.

Now that you understand how to look up groups from LDAP and map their information to Keycloak, it is time to understand how to map group hierarchy and user membership.

In LDAP, groups are usually organized in a hierarchy to represent your organizational tree. Keycloak allows you to map and preserve the group hierarchy by automatically creating it when you're fetching groups from LDAP. The first step is to set the attribute that was used to infer the relationship between the groups in the hierarchy using the Membership LDAP Attribute field. Keycloak is going to look up the children of a group by looking at the value of this attribute. Its format is usually the Fully Qualified Name (FQN) of another group entry.

Tip

You should still be able to set a different format for the membership attribute if you are still relying on memberUid to reference another group in the LDAP tree. For that, choose UID in the Membership Attribute Type field.

Keycloak also allows you to map user membership from LDAP so that when you're importing users, they are automatically assigned to the groups they belong to. For that, you can set different strategies for how this relationship is obtained from LDAP. The User Groups Retrieve Strategy field allows you to choose whether user membership should be fetched based on the member attribute of groups – similar to when fetching the group hierarchy – or whether membership should be fetched based on the presence of another attribute within the user entry in LDAP – usually, this is the memberOf attribute.

Regarding synchronization, the mapper allows you to have fine-grained control over how group information is kept in sync with your LDAP directory, as well as how groups should be imported into Keycloak.

If you are using a writable LDAP provider, the mapper defaults to writing back any changes you make to groups that have been imported from LDAP, including user membership. This behavior is managed through the Mode field, which provides different strategies on how group information should be imported and synced back to LDAP.

By default, groups that have been imported from LDAP are created as top-level groups in Keycloak. Sometimes, it might be useful to import groups into a specific group in Keycloak to differentiate them from local groups. For that, you can set the Groups Path field to any existing group you have in Keycloak.

In this section, you learned how to map group information using the group-ldap-mapper mapper. You also learned that Keycloak is very flexible regarding how this data is fetched and kept in sync with LDAP.

In the next section, we will be looking at how to map roles from LDAP.

Synchronizing roles

Like groups, roles are also mapped from LDAP using a specific mapper. To import role data, click on the Create button in the top-right corner of the mappers list.

Type in a name for the new mapper and select role-ldap-mapper from the Mapper Type field.

As you can see, the core settings for role mapping are pretty much the same ones that you learned about in the previous section. Mainly, they are related to configuring how Keycloak is going to look up entries in your LDAP tree.

In this section, we are going to focus on the behavior and the specific properties related to how Keycloak maps role information from LDAP.

Roles are automatically imported from Keycloak whenever the user authenticates in Keycloak. Keycloak also allows you to manually trigger a synchronization once you've created the mapper.

When importing roles, Keycloak defaults to creating these roles as realm roles, where users are automatically granted their roles in LDAP. This behavior is controlled by the Use Realm Roles Mapping field, which can also be disabled so that imported roles are created as client roles for a specific client in Keycloak.

In this section, you learned how to integrate Keycloak with LDAP and how users, groups, and role information can be obtained from it. You also learned that Keycloak is very flexible regarding mapping different types of information from LDAP through a functionality called LDAP mappers. Lastly, you learned that Keycloak gives you fine-grained control over how data is imported, as well as how data is replicated back to LDAP whenever you make changes to the information that's imported from LDAP.

In the next section, we are going to look at how to integrate with third-party identity providers by leveraging Keycloak as an identity broker to authenticate and replicate their users.

Integrating with third-party identity providers

Keycloak can integrate with third-party identity providers using a set of open standard protocols.

In the previous section, you learned about user federation and how to easily integrate with LDAP. Identity providers leverage user federation to create cross-domain trust between Keycloak and an identity provider, where the identity data about users is shared and used by Keycloak to create, authenticate, and authorize users.

Integration with third-party identity providers is possible by using Keycloak as an identity broker, where Keycloak acts as an intermediary service for authenticating and replicating users from a targeted identity provider.

Identity brokering can solve different types of problems. As we will see in the next section, it can be used to integrate with social providers, as an integration point to a legacy identity and access management system, or to share identity data between a business partner and your organization.

In Keycloak, you can integrate with two main types of identity providers, depending on the security protocol they support:

  • SAML v2
  • OpenID Connect v1.0

Through identity brokering, you can provide a much better experience for users, where they can leverage an existing account to authenticate and sign up in your realm. Once these users have been created and their information has been imported from the third-party provider, they become users of your realm and can enjoy all the features provided by Keycloak and respect the security constraints imposed by your realm.

In this section, we are going to look at how to create an OpenID Connect v1.0 identity provider. For simplicity, we are going to use another realm in the same Keycloak server to represent the third-party identity provider we are trying to integrate with. However, the same concepts and steps you are about to learn should be valid for any other OpenID Connect-compliant identity provider.

Creating a OpenID Connect identity provider

Firstly, create a realm in Keycloak called third-party-provider. In this realm, create a client with the following settings:

  • Client ID: broker-app
  • Root URL: http://localhost:8080/auth/realms/myrealm/broker/oidc/endpoint

After creating the broker-app client in Keycloak, change the Access Type settings on the client details page to Confidential.

Make sure to keep a note of the client secret that's generated as we are going to use it later when we configure the identity provider.

Now, create a user called third-party-user in the third-party-provider realm and make sure to set a password for them.

Now, let's create a new identity provider in the myrealm realm. For that, click on the Identity Providers link in the left-hand side menu:

Figure 10.8 – Creating a new identity provider

Figure 10.8 – Creating a new identity provider

The Identity Providers page allows you to either create a new provider or list all the providers that have been configured for a realm. If the realm does not have a provider yet, you will be prompted to select the type of the provider to create a new one.

Let's select OpenID Connect v1.0 from the list of providers. After that, you should be redirected to the provider settings page.

Note

On this page, you have a read-only Redirect URI field, whose value is the URL we set for the broker-app client as a root URL. This URL is the location where users are going to be redirected to once they've authenticated through the identity provider. In our case, users are going to be redirected back to the myrealm realm after successfully authenticating through the identity provider.

As you learned in Chapter 4, Authenticating Users with OpenID Connect, an OpenID Connect Provider (OP) advertises the endpoints that can be used to interact with them through a document available from a specific endpoint. By using this endpoint, we can quickly configure our identity provider, since most of the settings on the Provider settings page are going to be filled in automatically with the information from the OP you are integrating with.

At the bottom of the Provider settings page, there is an Import from URL field that you should set with the location where the OP is exposing its discovery document. In our case, this document is located at http://localhost:8080/auth/realms/third-party-provider/.well-known/openid-configuration.

After setting the URL, click on the Import button. Once you've done that, you should see that some of the other fields on this page were automatically populated with the information from the discovery document.

Now, let's fill in some additional information to finish configuring the provider. For that, fill in the following fields:

  • Display Name: My Third-Party Provider
  • Client Authentication: Client secret sent as post
  • Client ID: broker-app
  • Client Secret: <CLIENT_SECRET>

Finally, click on Save to create the identity provider.

Note

Note that both the Client ID and Client Secret fields refer to the broker-app client in the third-party-provider realm. This is the client used by the identity provider to authenticate users in that realm.

Now, let's test whether new users can authenticate and sign up to our realm using the newly created provider. For that, open your browser at http://localhost:8080/auth/realms/myrealm/account to access the account console:

Figure 10.9 – Login page with an option to authenticate using an identity provider

Figure 10.9 – Login page with an option to authenticate using an identity provider

Note that you will be presented with the option to authenticate with My Third-Party Provider, which is the provider we just created.

Click on the My Third-Party Provider button; you should be redirected to the third-party-provider realm to authenticate. At the login page, provide the username and password for the third-party-user user to log in.

If everything is working properly, you should be redirected to a page asking for additional information about the user. Fill in all the fields and click on the Submit button.

Once the user has been authenticated to the third-party provider, a set of tokens will be issued to Keycloak. These represent the user's identity and the permissions that have been granted to the user when authenticating to the third-party-provider realm. By looking at these tokens, Keycloak is capable of fetching user information and creating or updating the user in your realm.

Now, if you list the users that are available in the myrealm realm, you should see that the third-party-user user is among them. This means you can manage them just like any other user in your realm.

There are several settings you can choose from when configuring a provider. For instance, Keycloak can be used to store tokens that have been issued by an identity provider, a useful capability if you need to use these tokens to access APIs protected by the provider. Once stored, Keycloak allows you to obtain these tokens through another functionality called token exchange.

Keycloak also allows you to define a specific authentication flow when the user is authenticating for the first time using an identity provider. This is a powerful feature that allows you to gather additional information about your users or even force them to set up credentials.

Depending on your requirements, you can also configure your realm to only allow users to authenticate and link their accounts with an identity provider through the account console. This is achieved by turning on the Account Linking Only field. This ensures that users can't select the identity provider on the login page, only when they're in the account console.

There are many other settings you can choose from, and you can find them in the Keycloak documentation at https://www.keycloak.org/docs/latest/server_admin/#_identity_broker.

In this section, you learned how Keycloak can be used to integrate with third-party identity providers using open standard protocols. You also learned that Keycloak allows you to quickly integrate with any identity provider using either the OpenID Connect or SAML2 protocols. You also learned that this integration is possible since you can use Keycloak as an identity broker, where users are authenticated and created based on the information that's returned by these providers.

In the next section, you will learn about how to extend the concepts presented in this chapter to integrate your realm with different social providers.

Integrating with social identity providers

A common requirement for applications that use Keycloak is the possibility to authenticate users using different social providers, such as Google, GitHub, Instagram, and Twitter.

Integration with social providers follows the same principles that you learned about in the previous section, where Keycloak acts as a broker to authenticate and exchange identity data about users using a well-known and open standard security protocol.

To integrate with a social provider, click on the Identity Providers link in the left-hand side menu.

Keycloak allows you to select from different social providers. To integrate with them, you only need to fill in some information that you usually obtain from the social provider you are integrating with.

Let's configure GitHub as a social provider to allow users to authenticate using their GitHub account. Firstly, make sure you have a valid GitHub account. If not, you can create one at https://github.com.

Now, let's create a GitHub social provider in our realm by selecting GitHub from the list of available providers. Once you've selected GitHub, you should be presented with a page containing a few settings that you need to fill in to create the provider.

To use GitHub, we need to create an OAuth app at https://github.com/settings/developers. When creating the application, you will be asked to provide an authorization callback URL or redirect URL. This URL is the endpoint in Keycloak that is going to receive the response from GitHub once the user is successfully authenticated – or when an error occurs. When creating a social provider in Keycloak, you are given a redirect URI, which you should use to configure the application in GitHub. This URL is available from the Redirect URI field. Copy and paste the value of this field and use it to create the app in GitHub.

Depending on the social provider you are integrating with, you are going to be asked for additional information to make the integration possible. For GitHub, we need a client ID and client secret, both of which are provided by GitHub once you've created your app. Fill in both the Client ID and Client Secret fields with the values you got from GitHub.

Now, click on the Save button to create the provider.

Now, let's test whether the users in our realm can authenticate and sign up to our realm using the newly created provider. For that, open your browser at http://localhost:8080/auth/realms/myrealm/account to access the account console.

You should now be at the login page of Keycloak. Note that you will be presented with the option to authenticate with GitHub, the provider we just created. Click on the GitHub button to be redirected to GitHub to authenticate.

After authenticating with GitHub, you might be presented with a consent page, asking you to grant permissions to your realm for accessing information about the user. After approving the consent, Keycloak is going to create a user based on the information that was obtained from GitHub. You should be automatically authenticated and redirected to the account console.

In this section, you learned how Keycloak makes it easier to integrate with different social providers. By integrating with GitHub, you learned about the basic steps and concepts around integrating with any other social provider that supports the OpenID Connect or OAuth2 protocols.

In the next section, we are going to learn about how users can manage their data using the Keycloak Account Console.

Allowing users to manage their data

In the previous sections, you learned how to manage users through the admin console as an administrator. You also learned that users can self-register in a realm. However, one of the main capabilities of Keycloak is to also allow users to manage their own accounts through a service called Keycloak Account Console.

The Keycloak Account Console is a regular application provided by Keycloak and is where users can manage their own accounts. They can also do the following:

  • Update their user profile
  • Update their password
  • Enable second-factor authentication
  • View applications, including what applications they have authenticated to
  • View open sessions, including remotely signing out of other sessions

To access the account console, open http://localhost:8080/auth/realms/myrealm/account/ in a browser. You will be redirected to a welcome page, as follows:

Figure 10.10 – The Keycloak Account Console

Figure 10.10 – The Keycloak Account Console

To log into the account console, you should either click on any of the links on that page or click on the Sign In button in the top-right corner of the page. By doing any of these things, you should be redirected to the login page and, after providing the user credentials, you should be redirected back to the account console:

Figure 10.11 – Authenticating to the account console

Figure 10.11 – Authenticating to the account console

Once authenticated, users can view and manage different information about their accounts:

  • Personal Info: Allows users to manage profile information such as email, first name, and last name.
  • Account Security: Allows users to manage their credentials, as well as set up two-factor and multi-factor authentication using OTP and security devices, respectively. In this area, users should also be able to track their account activity.
  • Applications: Allows users to manage the applications they have logged in and logged out from, as well as the permissions that have been granted to applications.

As a regular application, Keycloak automatically creates an account client in your realm to allow users to authenticate and access their account data. When users are created in a realm, they are automatically granted a manage-account client role. This role belongs to the account client and controls whether a user should have access to the account console. To disable access to the account console for a user, change the role mappings for the user to remove this role.

Tip

You can also find the URL of the account console through the Keycloak admin console. In the admin console, click on Clients. From there, you will find the URL of the account console next to the account client.

As we will see in the following chapters, Keycloak allows you to customize the look and feel of the account console, as well as how information is presented and managed through it, allowing you to obtain and store additional information from users.

In this section, you learned how users can manage their accounts through the account console. You also learned that Keycloak allows you to control what users can view and manage in their accounts, by either relying on your realm settings or by managing the roles that have been granted to the user.

Summary

In this chapter, you were presented with the main aspects of user management in Keycloak. You learned that users can be created directly in Keycloak or by integrating with different third-party identity providers and external identity stores. You also learned that Keycloak enables these integrations by leveraging open standard protocols such as OpenID Connect, SAML, and LDAP. You also learned that users are provided with capabilities to sign up for a realm, either by enabling self-registration to a realm or by integrating with a third-party provider. Finally, you learned that users can also manage their accounts through the Keycloak Account Console.

In the next chapter, we are going to look at how users can authenticate using different credentials, as well as how Keycloak is the perfect fit for strong authentication.

Questions

  1. Can I integrate my own user database with Keycloak?
  2. Does Keycloak query the LDAP directory every time the user authenticates?
  3. How do I differentiate users that have been created using a third-party or social identity provider?

Further reading

For more information on the topics that were covered in this chapter, you can refer to the following links:

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
204.236.220.47