[
  {"id": "keycloak-features-and-concepts", "title": "Keycloak features and concepts", "breadcrumb": [], "url": "index.html#keycloak-features-and-concepts", "md": "md/keycloak-features-and-concepts.md", "text": "Keycloak is a single sign on solution for web apps and RESTful web services. The goal of Keycloak is to make security simple so that it is easy for application developers to secure the apps and services they have deployed in their organization. Security features that developers normally have to write for themselves are provided out of the box and are easily tailorable to the individual requirements of your organization. Keycloak provides customizable user interfaces for login, registration, administration, and account management. You can also use Keycloak as an integration platform to hook it into existing LDAP and Active Directory servers. You can also delegate authentication to third party identity providers like Facebook and Google."},
  {"id": "features", "title": "Features", "breadcrumb": ["Keycloak features and concepts"], "url": "index.html#features", "md": "md/features.md", "text": "Keycloak provides the following features:\nSingle Sign-On and Single Sign-Out for browser applications.\nOpenID Connect support.\nOAuth 2.0 support.\nSAML support.\nIdentity Brokering - Authenticate with external OpenID Connect or SAML Identity Providers.\nSocial Login - Enable login with Google, GitHub, Facebook, Twitter, and other social networks.\nUser Federation - Sync users from LDAP and Active Directory servers.\nKerberos bridge - Automatically authenticate users that are logged-in to a Kerberos server.\nAdmin Console for central management of users, roles, role mappings, clients and configuration.\nAccount Console that allows users to centrally manage their account.\nTheme support - Customize all user facing pages to integrate with your applications and branding.\nFlexible Authentication - Authenticate user with various mechanisms including passkey, password or X.509 certificates. Step-up authentication support\nTwo-factor Authentication - Support for passkey, recovery codes and TOTP/HOTP via Google Authenticator or FreeOTP.\nLogin flows - optional user self-registration, recover password, verify email, require password update, etc.\nSession management - Admins and users themselves can view and manage user sessions.\nToken mappers - Map user attributes, roles, etc. how you want into tokens and statements.\nNot-before revocation policies per realm, application and user.\nCORS support - Client adapters have built-in support for CORS.\nService Provider Interfaces (SPI) - A number of SPIs to enable customizing various aspects of the server. Authentication flows, user federation providers, protocol mappers and many more.\nSupports any platform/language that has an OpenID Connect Relying Party library or SAML 2.0 Service Provider library."},
  {"id": "basic-keycloak-operations", "title": "Basic Keycloak operations", "breadcrumb": ["Keycloak features and concepts"], "url": "index.html#basic-keycloak-operations", "md": "md/basic-keycloak-operations.md", "text": "Keycloak is a separate server that you manage on your network. Applications are configured to point to and be secured by this server. Keycloak uses open protocol standards like OpenID Connect or SAML 2.0 to secure your applications. Browser applications redirect a user’s browser from the application to the Keycloak authentication server where they enter their credentials. This redirection is important because users are completely isolated from applications and applications never see a user’s credentials. Applications instead are given an identity token or assertion that is cryptographically signed. These tokens can have identity information like username, address, email, and other profile data. They can also hold permission data so that applications can make authorization decisions. These tokens can also be used to make secure invocations on REST-based services."},
  {"id": "core-concepts-and-terms", "title": "Core concepts and terms", "breadcrumb": ["Keycloak features and concepts"], "url": "index.html#core-concepts-and-terms", "md": "md/core-concepts-and-terms.md", "text": "Consider these core concepts and terms before attempting to use Keycloak to secure your web applications and REST services.\nusers\nUsers are entities that are able to log into your system. They can have attributes associated with themselves like email, username, address, phone number, and birthday. They can be assigned group membership and have specific roles assigned to them.\nauthentication\nThe process of identifying and validating a user.\nauthorization\nThe process of granting access to a user.\ncredentials\nCredentials are pieces of data that Keycloak uses to verify the identity of a user. Some examples are passwords, one-time-passwords, digital certificates, or even fingerprints.\nroles\nRoles identify a type or category of user. Admin, user, manager, and employee are all typical roles that may exist in an organization. Applications often assign access and permissions to specific roles rather than individual users as dealing with users can be too fine-grained and hard to manage.\nuser role mapping\nA user role mapping defines a mapping between a role and a user. A user can be associated with zero or more roles. This role mapping information can be encapsulated into tokens and assertions so that applications can decide access permissions on various resources they manage.\ncomposite roles\nA composite role is a role that can be associated with other roles. For example a superuser composite role could be associated with the sales-admin and order-entry-admin roles. If a user is mapped to the superuser role they also inherit the sales-admin and order-entry-admin roles.\ngroups\nGroups manage groups of users. Attributes can be defined for a group. You can map roles to a group as well. Users that become members of a group inherit the attributes and role mappings that group defines.\nrealms\nA realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that"},
  {"id": "creating-first-admin_server_administration_guide", "title": "Creating the first administrator", "breadcrumb": [], "url": "index.html#creating-first-admin_server_administration_guide", "md": "md/creating-first-admin_server_administration_guide.md", "text": "After installing Keycloak, you need an administrator account that can act as a super admin with full permissions to manage Keycloak. With this account, you can log in to the Keycloak Admin Console where you create realms and users and register applications that are secured by Keycloak."},
  {"id": "creating-the-account-on-the-local-host", "title": "Creating the account on the local host", "breadcrumb": ["Creating the first administrator"], "url": "index.html#creating-the-account-on-the-local-host", "md": "md/creating-the-account-on-the-local-host.md", "text": "If your server is accessible from localhost, perform these steps.\nProcedure\nIn a web browser, go to the http://localhost:8080 URL.\nSupply a username and password that you can recall.\nWelcome page"},
  {"id": "creating-the-account-remotely", "title": "Creating the account remotely", "breadcrumb": ["Creating the first administrator"], "url": "index.html#creating-the-account-remotely", "md": "md/creating-the-account-remotely.md", "text": "If you cannot access the server from a localhost address or just want to start Keycloak from the command line, use the KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD environment variables to create an initial admin account.\nFor example:\nexport KC_BOOTSTRAP_ADMIN_USERNAME=<username>\nexport KC_BOOTSTRAP_ADMIN_PASSWORD=<password>\n\nbin/kc.[sh|bat] start"},
  {"id": "_configuring-realms", "title": "Configuring realms", "breadcrumb": [], "url": "index.html#_configuring-realms", "md": "md/_configuring-realms.md", "text": "Once you have an administrative account for the Admin Console, you can configure 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."},
  {"id": "using-the-admin-console", "title": "Using the Admin Console", "breadcrumb": ["Configuring realms"], "url": "index.html#using-the-admin-console", "md": "md/using-the-admin-console.md", "text": "You configure realms and perform most administrative tasks in the Keycloak Admin Console.\nPrerequisites\nTo use the Admin Console, you need an administrator account.\nIf no administrators exist, see Creating the first administrator.\nIf other administrators exist, ask an administrator to provide an account with privileges to manage realms.\nProcedure\nGo to the URL for the Admin Console.\nFor example, for localhost, use this URL: http://localhost:8080/admin/\nEnter the username and password you created on the Welcome Page or through environment variables as described in Creating the initial admin user.\nLogin page\nThis action displays the Admin Console.\nAdmin Console\nNote the menus and other options that you can use:\nClick the Current realm to see if other realms are available to be managed.\nClick Create realm to create another realm that you can manage.\nClick the top right list to view your account or log out.\nClick Realm settings in the menu to see the fields and options for this realm.\nClick a question mark ? icon to show the definition of a field such as Frontend URL.\nRealm settings\nExport files from the Admin Console are not suitable for backups or data transfer between servers. Only boot-time exports are suitable for backups or data transfer between servers."},
  {"id": "the-master-realm", "title": "The master realm", "breadcrumb": ["Configuring realms"], "url": "index.html#the-master-realm", "md": "md/the-master-realm.md", "text": "In the Admin Console, two types of realms exist:\nMaster realm - This realm was created for you when you first started Keycloak. It contains the administrator account you created at the first login. Use the master realm only to create and manage the realms in your system.\nOther realms - These realms are created by the administrator in the master realm. In these realms, administrators manage the users in your organization and the applications they need. The applications are owned by the users.\nRealms and applications\nRealms are isolated from one another and can only manage and authenticate the users that they control. Following this security model helps prevent accidental changes and follows the tradition of permitting user accounts access to only those privileges and powers necessary for the successful completion of their current task.\nAdditional resources\nSee Dedicated Realm Admin Consoles if you want to disable the master realm and define administrator accounts within any new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts."},
  {"id": "proc-creating-a-realm_server_administration_guide", "title": "Creating a realm", "breadcrumb": ["Configuring realms"], "url": "index.html#proc-creating-a-realm_server_administration_guide", "md": "md/proc-creating-a-realm_server_administration_guide.md", "text": "You create a realm to provide a management space where you can create users and give them permissions to use applications. At first login, you are typically in the master realm, the top-level realm from which you create other realms.\nWhen deciding what realms you need, consider the kind of isolation you want to have for your users and applications. For example, you might create a realm for the employees of your company and a separate realm for your customers. Your employees would log into the employee realm and only be able to visit internal company applications. Customers would log into the customer realm and only be able to interact with customer-facing apps.\nProcedure\nIn the Admin Console, click Create Realm next to Current realm.\nEnter a name for the realm.\nClick Create.\nCreate realm\nThe current realm is now set to the realm you just created. You can switch between realms by clicking the realm name in the menu."},
  {"id": "_ssl_modes", "title": "Configuring SSL for a realm", "breadcrumb": ["Configuring realms"], "url": "index.html#_ssl_modes", "md": "md/_ssl_modes.md", "text": "Each realm has an associated SSL Mode, which defines the SSL/HTTPS requirements for interacting with the realm. Browsers and applications that interact with the realm honor the SSL/HTTPS requirements defined by the SSL Mode or they cannot interact with the server.\nProcedure\nClick Realm settings in the menu.\nClick the General tab.\nGeneral tab\nSet Require SSL to one of the following SSL modes:\nExternal requests Users can interact with Keycloak without SSL so long as they stick to private IPv4 addresses such as localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x, 172.16.x.x or IPv6 link-local and unique-local addresses. If you try to access Keycloak without SSL from a non-private IP address, you will get an error.\nNone Keycloak does not require SSL. This choice applies only in development when you are experimenting and do not plan to support this deployment.\nAll requests Keycloak requires SSL for all IP addresses."},
  {"id": "_email", "title": "Configuring email for a realm", "breadcrumb": ["Configuring realms"], "url": "index.html#_email", "md": "md/_email.md", "text": "Keycloak sends emails to users to verify their email addresses, when they forget their passwords, or when an administrator needs to receive notifications about a server event. To enable Keycloak to send emails, you provide Keycloak with your SMTP server settings.\nProcedure\nClick Realm settings in the menu.\nClick the Email tab.\nEmail tab\nFill in the fields and toggle the switches as needed.\nTemplate\nFrom\nFrom denotes the address used for the From SMTP-Header for the emails sent.\nFrom display name\nFrom display name allows to configure a user-friendly email address aliases (optional). If not set the plain From email address will be displayed in email clients.\nReply to\nReply to denotes the address used for the Reply-To SMTP-Header for the mails sent (optional). If not set the plain From email address will be used.\nReply to display name\nReply to display name allows to configure a user-friendly email address aliases (optional). If not set the plain Reply To email address will be displayed.\nEnvelope from\nEnvelope from denotes the Bounce Address used for the Return-Path SMTP-Header for the mails sent (optional).\nConnection & Authentication\nHost\nHost denotes the SMTP server hostname used for sending emails.\nPort\nPort denotes the SMTP server port.\nEncryption\nTick one of these checkboxes to support sending emails for recovering usernames and passwords, especially if the SMTP server is on an external network. You will most likely need to change the Port to 465, the default port for SSL/TLS.\nAuthentication\nSet this switch to ON if your SMTP server requires authentication.\nUsername\nAll authentication-mechanisms require a username.\nAuthentication Type\nChoose the kind of authentication: 'password' or 'token'.\nPassword\nOnly needed when Authentication Type 'password' is selected. Supply the Password. The value of the Password field can refer a value from an external vault.\nAuth Token URL\nOnly needed when Authentication Type 'token' is selected. Supply the Auth Token URL that is used"},
  {"id": "_themes", "title": "Configuring themes", "breadcrumb": ["Configuring realms"], "url": "index.html#_themes", "md": "md/_themes.md", "text": "For a given realm, you can change the appearance of any UI in Keycloak by using themes.\nProcedure\nClick Realm settings in the menu.\nClick the Themes tab.\nThemes tab\nPick the theme you want for each UI category and click Save.\nLogin theme\nUsername password entry, OTP entry, new user registration, and other similar screens related to login.\nAccount theme\nThe console used by the user to manage his or her account.\nAdmin console theme\nThe skin of the Keycloak Admin Console.\nEmail theme\nWhenever Keycloak has to send out an email, it uses templates defined in this theme to craft the email.\nAdditional resources\nFor details on creating or modifying themes, see Deploying Themes in the UI Customization Guide."},
  {"id": "enabling-internationalization", "title": "Enabling internationalization", "breadcrumb": ["Configuring realms"], "url": "index.html#enabling-internationalization", "md": "md/enabling-internationalization.md", "text": "Every UI screen is internationalized in Keycloak. The default language is English, but you can choose which locales you want to support and what the default locale will be.\nProcedure\nClick Realm Settings in the menu.\nClick the Localization tab.\nEnable Internationalization.\nSelect the languages you will support.\nLocalization tab\nThe next time a user logs in, that user can choose a language on the login page to use for the login screens, Account Console, and Admin Console.\nAdditional resources\nThe Server Developer Guide explains how you can offer additional languages. All internationalized texts which are provided by the theme can be overwritten by realm-specific texts on the Localization tab.\nUser locale selection\nA locale selector provider suggests the best locale on the information available. However, it is often unknown who the user is. For this reason, the previously authenticated user’s locale is remembered in a persisted cookie.\nThe logic for selecting the locale uses the first of the following that is available:\nUser selected - when the user has selected a locale using the drop-down locale selector\nUser profile - when there is an authenticated user and the user has a preferred locale set\nClient selected - passed by the client using for example ui_locales parameter\nCookie - last locale selected on the browser\nAccepted language - locale from Accept-Language header\nRealm default\nIf none of the above, fall back to English\nWhen a user is authenticated an action is triggered to update the locale in the persisted cookie mentioned earlier. If the user has actively switched the locale through the locale selector on the login pages the users locale is also updated at this point.\nIf you want to change the logic for selecting the locale, you have an option to create custom LocaleSelectorProvider. For details, please refer to the Working with themes: Locale selector."},
  {"id": "controlling-login-options", "title": "Controlling login options", "breadcrumb": ["Configuring realms"], "url": "index.html#controlling-login-options", "md": "md/controlling-login-options.md", "text": "Keycloak includes several built-in login page features.\nEnabling forgot password\nIf you enable Forgot password, users can reset their login credentials if they forget their passwords or lose their OTP generator.\nProcedure\nClick Realm settings in the menu.\nClick the Login tab.\nLogin tab\nToggle Forgot password to ON.\nA Forgot Password? link displays in your login pages.\nForgot password link\nSpecify Host and From in the Email tab in order for Keycloak to be able to send the reset email.\nClick this link to bring users where they can enter their username or email address and receive an email with a link to reset their credentials.\nForgot password page\nThe text sent in the email is configurable. See Server Developer Guide for more information.\nWhen users click the email link, Keycloak asks them to update their password, and if they have set up an OTP generator, Keycloak asks them to reconfigure the OTP generator. For security reasons, the flow forces federated users to login again after the reset credentials and keeps internal database users logged in if the same authentication session (same browser) is used. Depending on the security requirements of your organization, you can change the default behavior.\nTo change this behavior, perform these steps:\nProcedure\nClick Authentication in the menu.\nClick the Flows tab.\nSelect the Reset Credentials flow.\nReset credentials flow\nIf you do not want to reset the OTP, set the Reset - Conditional OTP sub-flow requirement to Disabled.\nSend Reset Email Configuration\nIf you want to change default behavior for the force login option, click the Send Reset Email settings icon in the flow, define an Alias, and select the best Force login after reset option for you (true, always force re-authentication, false, keep the user logged in if the same browser was used, only-federated, default value that forces login again only for federated users).\nClick Authentication in the menu.\nClick the Required actions tab.\nEnsure Update Password is enabled."},
  {"id": "realm_keys", "title": "Configuring realm keys", "breadcrumb": ["Configuring realms"], "url": "index.html#realm_keys", "md": "md/realm_keys.md", "text": "The authentication protocols that are used by Keycloak require cryptographic signatures and sometimes encryption. Keycloak uses asymmetric key pairs, a private and public key, to accomplish this.\nKeycloak has a single active key pair at a time, but can have several passive keys as well. The active key pair is used to create new signatures, while the passive key pair can be used to verify previous signatures. This makes it possible to regularly rotate the keys without any downtime or interruption to users.\nWhen a realm is created, a key pair and a self-signed certificate is automatically generated.\nProcedure\nClick Realm settings in the menu.\nClick Keys.\nSelect Passive keys from the filter dropdown to view passive keys.\nSelect Disabled keys from the filter dropdown to view disabled keys.\nA key pair can have the status Active, but still not be selected as the currently active key pair for the realm. The selected active pair which is used for signatures is selected based on the first key provider sorted by priority that is able to provide an active key pair.\nRotating keys\nWe recommend that you regularly rotate keys. Start by creating new keys with a higher priority than the existing active keys. You can instead create new keys with the same priority and making the previous keys passive.\nOnce new keys are available, all new tokens and cookies will be signed with the new keys. When a user authenticates to an application, the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed new tokens are signed with the new keys. Eventually, all cookies and tokens use the new keys and after a while the old keys can be removed.\nThe frequency of deleting old keys is a tradeoff between security and making sure all cookies and tokens are updated. Consider creating new keys every three to six months and deleting old keys one to two months after you create the new keys. If a user was inactive in the period between the new keys being added and the old keys"},
  {"id": "_user-storage-federation", "title": "Using external storage", "breadcrumb": [], "url": "index.html#_user-storage-federation", "md": "md/_user-storage-federation.md", "text": "Organizations can have databases containing information, passwords, and other credentials. Typically, you cannot migrate existing data storage to a Keycloak deployment so Keycloak can federate existing external user databases. Keycloak supports LDAP and Active Directory, but you can also code extensions for any custom user database by using the Keycloak User Storage SPI.\nWhen a user attempts to log in, Keycloak examines that user’s storage to find that user. If Keycloak does not find the user, Keycloak iterates over each User Storage provider for the realm until it finds a match. Data from the external data storage then maps into a standard user model the Keycloak runtime consumes. This user model then maps to OIDC token claims and SAML assertion attributes.\nExternal user databases rarely have the data necessary to support all the features of Keycloak, so the User Storage Provider can opt to store items locally in Keycloak user data storage. Providers can import users locally and sync periodically with external data storage. This approach depends on the capabilities of the provider and the configuration of the provider. For example, your external user data storage may not support OTP. The OTP can be handled and stored by Keycloak, depending on the provider."},
  {"id": "adding-a-provider", "title": "Adding a provider", "breadcrumb": ["Using external storage"], "url": "index.html#adding-a-provider", "md": "md/adding-a-provider.md", "text": "To add a storage provider, perform the following procedure:\nProcedure\nClick User Federation in the menu.\nUser federation\nChoose to add a Kerberos or LDAP provider\nKeycloak brings you to that provider’s configuration page."},
  {"id": "dealing-with-provider-failures", "title": "Dealing with provider failures", "breadcrumb": ["Using external storage"], "url": "index.html#dealing-with-provider-failures", "md": "md/dealing-with-provider-failures.md", "text": "If a User Storage Provider fails, you may not be able to log in and view users in the Admin Console. Keycloak does not detect failures when using a Storage Provider to look up a user, so it cancels the invocation. If you have a Storage Provider with a high priority that fails during user lookup, the login or user query fails with an exception and will not fail over to the next configured provider.\nKeycloak searches the local Keycloak user database first to resolve users before any LDAP or custom User Storage Provider. Consider creating an administrator account stored in the local Keycloak user database in case of problems connecting to your LDAP and back ends.\nEach LDAP and custom User Storage Provider has an enable toggle on its Admin Console page. Disabling the User Storage Provider skips the provider when performing queries, so you can view and log in with user accounts in a different provider with lower priority. If your provider uses an import strategy and is disabled, imported users are still available for lookup in read-only mode.\nWhen a Storage Provider lookup fails, Keycloak does not fail over because user databases often have duplicate usernames or duplicate emails between them. Duplicate usernames and emails can cause problems because the user loads from one external data store when the admin expects them to load from another data store."},
  {"id": "_ldap", "title": "Lightweight Directory Access Protocol (LDAP) and Active Directory", "breadcrumb": ["Using external storage"], "url": "index.html#_ldap", "md": "md/_ldap.md", "text": "Keycloak includes an LDAP/AD provider. You can federate multiple different LDAP servers in one Keycloak realm and map LDAP user attributes into the Keycloak common user model.\nBy default, Keycloak maps the username, email, first name, and last name of the user account, but you can also configure additional mappings. Keycloak’s LDAP/AD provider supports password validation using LDAP/AD protocols and storage, edit, and synchronization modes.\nConfiguring federated LDAP storage\nProcedure\nClick User Federation in the menu.\nUser federation\nClick Add LDAP providers.\nKeycloak brings you to the LDAP configuration page.\nAdd LDAP provider\nStorage mode\nKeycloak imports users from LDAP into the local Keycloak user database. This copy of the user database synchronizes on-demand or through a periodic background task. An exception exists for synchronizing passwords. Keycloak never imports passwords. Password validation always occurs on the LDAP server.\nThe advantage of synchronization is that all Keycloak features work efficiently because any required extra per-user data is stored locally. The disadvantage is that each time Keycloak queries a specific user for the first time, Keycloak performs a corresponding database insert. Also, when imported users are returned as part of a search operation, a corresponding LDAP search is performed for each one to check if the user still exists in LDAP and do some basic validation.\nYou can synchronize the import with your LDAP server. Import synchronization is unnecessary when LDAP mappers always read particular attributes from the LDAP rather than the database.\nYou can use LDAP with Keycloak without importing users into the Keycloak user database. The LDAP server backs up the common user model that the Keycloak runtime uses. If LDAP does not support data that a Keycloak feature requires, that feature will not work. The advantage of this approach is that you do not have the resource usage of importing and synchronizing copies of LDAP users"},
  {"id": "_sssd", "title": "SSSD and FreeIPA Identity Management integration", "breadcrumb": ["Using external storage"], "url": "index.html#_sssd", "md": "md/_sssd.md", "text": "Keycloak includes the System Security Services Daemon (SSSD) plugin. SSSD is part of the Fedora and Red Hat Enterprise Linux (RHEL), and it provides access to multiple identities and authentication providers. SSSD also provides benefits such as failover and offline support. For more information, see Configuring SSSD.\nSSSD integrates with the FreeIPA identity management (IdM) server, providing authentication and access control. With this integration, Keycloak can authenticate against privileged access management (PAM) services and retrieve user data from SSSD. For more information about using Red Hat Identity Management in Linux environments, see the Red Hat Enterprise Linux Identity Management documentation.\nKeycloak and SSSD communicate through read-only D-Bus interfaces. For this reason, the way to provision and update users is to use the FreeIPA/IdM administration interface. By default, the interface imports the username, email, first name, and last name.\nKeycloak registers groups and roles automatically but does not synchronize them. The groups are imported from SSSD the first time the user is accessed and then they are managed entirely inside Keycloak. Any changes made by the administrator in Keycloak do not synchronize with SSSD or vice-versa.\nFreeIPA/IdM server\nThe FreeIPA Container image is available at Quay.io. To set up the FreeIPA server, see the FreeIPA documentation.\nProcedure\nRun your FreeIPA server using this command:\n docker run --name freeipa-server-container -it \\\n -h server.freeipa.local -e PASSWORD=YOUR_PASSWORD \\\n -v /sys/fs/cgroup:/sys/fs/cgroup:ro \\\n -v /var/lib/ipa-data:/data:Z freeipa/freeipa-server\nThe parameter -h with server.freeipa.local represents the FreeIPA/IdM server hostname. Change YOUR_PASSWORD to a password of your own.\nAfter the container starts, change the /etc/hosts file to include:\nx.x.x.x     server.freeipa.local\nIf you do not make this change, you must set up a DNS server.\nUse the following command to enroll your Linux"},
  {"id": "custom-providers", "title": "Custom providers", "breadcrumb": ["Using external storage"], "url": "index.html#custom-providers", "md": "md/custom-providers.md", "text": "Keycloak does have a Service Provider Interface (SPI) for User Storage Federation to develop custom providers. You can find documentation on developing customer providers in the Server Developer Guide."},
  {"id": "assembly-managing-users_server_administration_guide", "title": "Managing users", "breadcrumb": [], "url": "index.html#assembly-managing-users_server_administration_guide", "md": "md/assembly-managing-users_server_administration_guide.md", "text": "From the Admin Console, you have a wide range of actions you can perform to manage users."},
  {"id": "proc-creating-user_server_administration_guide", "title": "Creating users", "breadcrumb": ["Managing users"], "url": "index.html#proc-creating-user_server_administration_guide", "md": "md/proc-creating-user_server_administration_guide.md", "text": "You create users in the realm where you intend to have applications needed by those users. Avoid creating users in the master realm, which is only intended for creating other realms.\nPrerequisite\nYou are in a realm other than the master realm.\nProcedure\nClick Users in the menu.\nClick Add User.\nEnter the details for the new user.\nUsername is the only required field.\nClick Save. After saving the details, the Management page for the new user is displayed."},
  {"id": "user-profile", "title": "Managing user attributes", "breadcrumb": ["Managing users"], "url": "index.html#user-profile", "md": "md/user-profile.md", "text": "In Keycloak a user is associated with a set of attributes. These attributes are used to better describe and identify users within Keycloak as well as to pass over additional information about them to applications.\nA user profile defines a well-defined schema for representing user attributes and how they are managed within a realm. By providing a consistent view over user information, it allows administrators to control the different aspects on how attributes are managed as well as to make it much easier to extend Keycloak to support additional attributes.\nAlthough the user profile is mainly targeted for attributes that end-users can manage (e.g.: first and last names, phone, etc) it also serves for managing any other metadata you want to associate with your users.\nAmong other capabilities, user profile enables administrators to:\nDefine a schema for user attributes\nDefine whether an attribute is required based on contextual information (e.g.: if required only for users, or admins, or both, or depending on the scope being requested.)\nDefine specific permissions for viewing and editing user attributes, making possible to adhere to strong privacy requirements where some attributes can not be seen or be changed by third-parties (including administrators)\nDynamically enforce user profile compliance so that user information is always updated and in compliance with the metadata and rules associated with attributes\nDefine validation rules on a per-attribute basis by leveraging the built-in validators or writing custom ones\nDynamically render forms that users interact with like registration, update profile, brokering, and personal information in the account console, according to the attribute definitions and without any need to manually change themes.\nCustomize user management interfaces in the administration console so that attributes are rendered dynamically based on the user profile schema\nThe user profile schema or configuration uses a JSON format to represent attributes"},
  {"id": "ref-user-credentials_server_administration_guide", "title": "Defining user credentials", "breadcrumb": ["Managing users"], "url": "index.html#ref-user-credentials_server_administration_guide", "md": "md/ref-user-credentials_server_administration_guide.md", "text": "You can manage credentials of a user in the Credentials tab.\nCredential management\nYou change the priority of credentials by dragging and dropping rows. The new order determines the priority of the credentials for that user. The topmost credential has the highest priority. The priority determines which credential is displayed first after a user logs in.\nType\nThis column displays the type of credential, for example password or OTP.\nUser Label\nThis is an assignable label to recognize the credential when presented as a selection option during login. It can be set to any value to describe the credential.\nData\nThis is the non-confidential technical information about the credential. It is hidden, by default. You can click Show data…​ to display the data for a credential.\nActions\nClick Reset password to change the password for the user and Delete to remove the credential.\nYou cannot configure other types of credentials for a specific user in the Admin Console; that task is the user’s responsibility.\nYou can delete the credentials of a user in the event a user loses an OTP device or if credentials have been compromised. You can only delete credentials of a user in the Credentials tab.\nSetting a password for a user\nIf a user does not have a password, or if the password has been deleted, the Set Password section is displayed.\nIf a user already has a password, it can be reset in the Reset Password section.\nProcedure\nClick Users in the menu. The Users page is displayed.\nSelect a user.\nClick the Credentials tab.\nType a new password in the Set Password section.\nClick Set Password.\nIf Temporary is ON, the user must change the password at the first login. To allow users to keep the password supplied, set Temporary to OFF. The user must click Set Password to change the password.\nRequesting a user reset a password\nYou can also request that the user reset the password.\nProcedure\nClick Users in the menu. The Users page is displayed.\nSelect a user.\nClick the Credentials tab.\nClick"},
  {"id": "con-user-registration_server_administration_guide", "title": "Allowing users to self-register", "breadcrumb": ["Managing users"], "url": "index.html#con-user-registration_server_administration_guide", "md": "md/con-user-registration_server_administration_guide.md", "text": "You can use Keycloak as a third-party authorization server to manage application users, including users who self-register. If you enable self-registration, the login page displays a registration link so that user can create an account.\nRegistration link\nA user must add profile information to the registration form to complete registration. The registration form can be customized by removing or adding the fields that must be completed by a user.\nClarification on identity brokering and admin API\nEven when self-registrations is disabled, new users can be still added to Keycloak by either:\nAdministrator can add new users with the usage of admin console (or admin REST API)\nWhen identity brokering is enabled, new users authenticated by identity provider may be automatically added/registered in Keycloak storage. See the First login flow section in the Identity Brokering chapter for more information.\nAlso users coming from the 3rd-party user storage (for example LDAP) are automatically available in Keycloak when the particular user storage is enabled\nClarification on verify email\nWhen self-registrations is enabled together with Verify email realm switch, then password will not be set by default on the registration form. User will need first to verify his email and he will be able to setup his password on the subsequent screen. This is recommended for security reason, so that self-registered user can set his password or other credentials after verifying email. Note it is also recommended to enable Forget password, so that if user fails to verify his email during self-registration, he can do it later by following Forget password flow without being stuck.\nIf you still prefer to keep password on the initial registration form and make email verification to be done once user self-registers with his password, you can setup the configuration option on the Registration authentication flow. It can be done in the admin console by following tab Authentication → flow registration (or"},
  {"id": "con-required-actions_server_administration_guide", "title": "Defining actions required at login", "breadcrumb": ["Managing users"], "url": "index.html#con-required-actions_server_administration_guide", "md": "md/con-required-actions_server_administration_guide.md", "text": "You can set the actions that a user must perform at the first login. These actions are required after the user provides credentials. After the first login, these actions are no longer required. You add required actions on the Details tab of that user.\nSome required actions are automatically triggered for the user during login even if they are not explicitly added to this user by the administrator. For example Update password action can be triggered if Password policies are configured in a way that the user password needs to be changed every X days. Or verify profile action can require the user to update the User profile as long as some user attributes do not match the requirements according to the user profile configuration.\nThe following are examples of required action types:\nUpdate Password\nThe user must change their password.\nConfigure OTP\nThe user must configure a one-time password generator on their mobile device using either the Free OTP or Google Authenticator application.\nVerify Email\nThe user must verify their email account. An email will be sent to the user with a validation link that they must click. Once this workflow is successfully completed, the user will be allowed to log in.\nUpdate Profile\nThe user must update profile information, such as name, address, email, and phone number.\nSome actions do not makes sense to be added to the user account directly. For example, the Update User Locale is a helper action to handle some localization related parameters. Another example is the Delete Credential action, which is supposed to be triggered as a Parameterized AIA. Regarding this one, if the administrator wants to delete the credential of some user, that administrator can do it directly in the Admin Console. The Delete Credential action is dedicated to be used for example by the Keycloak Account Console.\nSetting required actions for one user\nYou can set the actions that are required for any user.\nProcedure\nClick Users in the menu.\nSelect a user from the"},
  {"id": "con-aia_server_administration_guide", "title": "Application initiated actions", "breadcrumb": ["Managing users"], "url": "index.html#con-aia_server_administration_guide", "md": "md/con-aia_server_administration_guide.md", "text": "Application initiated actions (AIA) allow client applications to request a user to perform an action on the Keycloak side. Usually, when an OIDC client application wants a user to log in, it redirects that user to the login URL as described in the OIDC section. After login, the user is redirected back to the client application. The user performs the actions that were required by the administrator as described in the previous section and then is immediately redirected back to the application. However, AIA allows the client application to request some required actions from the user during login. This can be done even if the user is already authenticated on the client and has an active SSO session. It is triggered by adding the kc_action parameter to the OIDC login URL with the value containing the requested action. For instance kc_action=UPDATE_PASSWORD parameter.\nA user may cancel an application initiated action. In this case the user is redirected back to the client application. The redirect URI will contain the query parameters kc_action_status=cancelled and kc_action with the name of the cancelled action.\nThe kc_action and kc_action_status parameters are a Keycloak proprietary mechanism unsupported by the OIDC specification.\nApplication initiated actions are supported only for OIDC clients.\nSo if AIA is used, an example flow is similar to the following:\nA client application redirects the user to the OIDC login URL with the additional parameter such as kc_action=UPDATE_PASSWORD\nThere is a browser flow always triggered as described in the Authentication flows section. If the user was not authenticated, that user needs to authenticate as during normal login. In case the user was already authenticated, that user might be automatically re-authenticated by an SSO cookie without needing to actively re-authenticate and supply the credentials again. In this case, that user will be directly redirected to the screen with the particular action (update password in this case)."},
  {"id": "proc-searching-user_server_administration_guide", "title": "Searching for a user", "breadcrumb": ["Managing users"], "url": "index.html#proc-searching-user_server_administration_guide", "md": "md/proc-searching-user_server_administration_guide.md", "text": "Search for a user to view detailed information about the user, such as the user’s groups and roles.\nPrerequisite\nYou are in the realm where the user exists.\nDefault search\nProcedure\nClick Users in the main menu. This Users page is displayed.\nType the full name, last name, first name, or email address of the user you want to search for in the search box. The search returns all users that match your criteria.\nThe criteria used to match users depends on the syntax used on the search box:\n\"somevalue\" → performs exact search of the string \"somevalue\";\n*somevalue* → performs infix search, akin to a LIKE '%somevalue%' DB query;\nsomevalue* or somevalue → performs prefix search, akin to a LIKE 'somevalue%' DB query.\nSearch by fields\nKeycloak supports direct user lookups for selected fields by prefixing the search term in the search box:\nid:myUUID → performs an exact user lookup by id for \"myUUID\";\nusername:myuser → performs an exact user lookup by username for \"myuser\";\nemail:myuser@domain.org → performs an exact user lookup by email for \"myuser@domain.org\".\nMultiple values can be supplied separated by whitespace (for example id:uuid1 uuid2) to look up several users in a single request.\nAttribute search\nProcedure\nClick Users in the main menu. This Users page is displayed.\nClick Default search button and switch it to Attribute search.\nClick Select attributes button and specify the attributes to search by.\nCheck Exact search checkbox to perform exact match or keep it unchecked to use an infix search for attribute values.\nClick Search button to perform the search. It returns all users that match the criteria.\nSearches performed in the Users page encompass both Keycloak’s database and configured user federation backends, such as LDAP. Users found in federated backends will be imported into Keycloak’s database if they don’t already exist there.\nAdditional Resources\nFor more information on user federation, see User Federation."},
  {"id": "proc-deleting-user_server_administration_guide", "title": "Deleting a user", "breadcrumb": ["Managing users"], "url": "index.html#proc-deleting-user_server_administration_guide", "md": "md/proc-deleting-user_server_administration_guide.md", "text": "You can delete a user, who no longer needs access to applications. If a user is deleted, the user profile and data is also deleted.\nProcedure\nClick Users in the menu. The Users page is displayed.\nClick View all users to find a user to delete.\nAlternatively, you can use the search bar to find a user.\nClick Delete from the action menu next to the user you want to remove and confirm deletion."},
  {"id": "proc-allow-user-to-delete-account_server_administration_guide", "title": "Enabling account deletion by users", "breadcrumb": ["Managing users"], "url": "index.html#proc-allow-user-to-delete-account_server_administration_guide", "md": "md/proc-allow-user-to-delete-account_server_administration_guide.md", "text": "End users and applications can delete their accounts in the Account Console if you enable this capability in the Admin Console. Once you enable this capability, you can give that capability to specific users.\nEnabling the Delete Account Capability\nYou enable this capability on the Required Actions tab.\nProcedure\nClick Authentication in the menu.\nClick the Required Actions tab.\nSelect Enabled on the Delete Account row.\nDelete account on required actions tab\nGiving a user the delete-account role\nYou can give specific users a role that allows account deletion.\nProcedure\nClick Users in the menu.\nSelect a user.\nClick the Role Mappings tab.\nClick the Assign role button.\nClick account delete-account.\nClick Assign.\nDelete-account role\nDeleting your account\nOnce you have the delete-account role, you can delete your own account.\nLog into the Account Console.\nAt the bottom of the Personal Info page, click Delete Account.\nDelete account page\nEnter your credentials and confirm the deletion.\nDelete confirmation\nThis action is irreversible. All your data in Keycloak will be removed."},
  {"id": "con-user-impersonation_server_administration_guide", "title": "Impersonating a user", "breadcrumb": ["Managing users"], "url": "index.html#con-user-impersonation_server_administration_guide", "md": "md/con-user-impersonation_server_administration_guide.md", "text": "An administrator with the appropriate permissions can impersonate a user. For example, if a user experiences a bug in an application, an administrator can impersonate the user to investigate or duplicate the issue.\nAny user with the impersonation role in the realm can impersonate a user.\nProcedure\nClick Users in the menu.\nClick a user to impersonate.\nFrom the Actions list, select Impersonate.\nIf the administrator and the user are in the same realm, then the administrator will be logged out and automatically logged in as the user being impersonated.\nIf the administrator and user are in different realms, the administrator will remain logged in, and additionally will be logged in as the user in that user’s realm.\nIn both instances, the Account Console of the impersonated user is displayed.\nAdditional resources\nFor more information on assigning administration permissions, see the Admin Console Access Control chapter."},
  {"id": "proc-enabling-recaptcha_server_administration_guide", "title": "Enabling reCAPTCHA", "breadcrumb": ["Managing users"], "url": "index.html#proc-enabling-recaptcha_server_administration_guide", "md": "md/proc-enabling-recaptcha_server_administration_guide.md", "text": "To safeguard registration against bots, Keycloak has integration with Google reCAPTCHA (see Setting up Google reCAPTCHA) and reCAPTCHA Enterprise (see Setting up Google reCAPTCHA Enterprise). The default theme (register.ftl) supports both v2 (visible, checkbox-based) and v3 (score-based, invisible) reCAPTCHA (see Choose the appropriate reCAPTCHA key type).\nSetting up Google reCAPTCHA\nEnter the following URL in a browser:\nhttps://www.google.com/recaptcha/admin/create\nCreate a reCAPTCHA and choose between Challenge v2 (visible checkbox) or Score-based, v3 (invisible) to get your reCAPTCHA site key and secret. Note them down for future use in this procedure.\nlocalhost domains are not supported by default. If you wish to continue supporting them for development you can add them to the list of supported domains for your site key.\nNavigate to the Keycloak admin console.\nClick Authentication in the menu.\nClick the Flows tab.\nSelect Registration from the list.\nSet the reCAPTCHA requirement to Required. This enables reCAPTCHA.\nClick the gear icon ⚙️ on the reCAPTCHA row.\nreCAPTCHA config\nEnter the reCAPTCHA Site Key generated from the Google reCAPTCHA website.\nEnter the reCAPTCHA Secret generated from the Google reCAPTCHA website.\nToggle reCAPTCHA v3 according to your Site Key type: on for score-based reCAPTCHA (v3), off for challenge reCAPTCHA (v2).\n(Optional) Toggle Use recaptcha.net to use www.recaptcha.net instead of www.google.com domain for cookies. See reCAPTCHA faq for more information.\nAuthorize Google to use the registration page as an iframe.\nIn Keycloak, websites cannot include a login page dialog in an iframe. This restriction is to prevent clickjacking attacks. You need to change the default HTTP response headers that is set in Keycloak.\nClick Realm Settings in the menu.\nClick the Security Defenses tab.\nEnter https://www.google.com in the field for the X-Frame-Options header (or https//www.recaptcha.net if you enabled Use recaptcha.net).\nEnter"},
  {"id": "ref-personal-data-collected_server_administration_guide", "title": "Personal data collected by Keycloak", "breadcrumb": ["Managing users"], "url": "index.html#ref-personal-data-collected_server_administration_guide", "md": "md/ref-personal-data-collected_server_administration_guide.md", "text": "By default, Keycloak collects the following data:\nBasic user profile data, such as the user email, first name, and last name.\nBasic user profile data used for social accounts and references to the social account when using a social login.\nDevice information collected for audit and security purposes, such as the IP address, operating system name, and the browser name.\nThe information collected in Keycloak is highly customizable. The following guidelines apply when making customizations:\nRegistration and account forms can contain custom fields, such as birthday, gender, and nationality. An administrator can configure Keycloak to retrieve data from a social provider or a user storage provider such as LDAP.\nKeycloak collects user credentials, such as password, OTP codes, and WebAuthn public keys. This information is encrypted and saved in a database, so it is not visible to Keycloak administrators. Each type of credential can include non-confidential metadata that is visible to administrators such as the algorithm that is used to hash the password and the number of hash iterations used to hash the password.\nWith authorization services and UMA support enabled, Keycloak can hold information about some objects for which a particular user is the owner."},
  {"id": "managing-user-sessions", "title": "Managing user sessions", "breadcrumb": [], "url": "index.html#managing-user-sessions", "md": "md/managing-user-sessions.md", "text": "When users log into realms, Keycloak maintains a user session for each user and remembers each client visited by the user within the session. Realm administrators can perform multiple actions on each user session:\nView login statistics for the realm.\nView active users and where they logged in.\nLog a user out of their session.\nRevoke tokens.\nSet up token timeouts.\nSet up session timeouts."},
  {"id": "administering-sessions", "title": "Administering sessions", "breadcrumb": ["Managing user sessions"], "url": "index.html#administering-sessions", "md": "md/administering-sessions.md", "text": "To see a top-level view of the active clients and sessions in Keycloak, click Sessions from the menu.\nSessions\nSigning out all active sessions\nYou can sign out all users in the realm. From the Action list, select Sign out all active sessions. All SSO cookies become invalid. Keycloak notifies clients by using the Keycloak OIDC client adapter of the logout event. Clients requesting authentication within active browser sessions must log in again. Client types such as SAML do not receive a back-channel logout request.\nClicking Sign out all active sessions does not revoke outstanding access tokens. Outstanding tokens must expire naturally. For clients using the Keycloak OIDC client adapter, you can push a revocation policy to revoke the token, but this does not work for other adapters.\nViewing client sessions\nProcedure\nClick Clients in the menu.\nClick a client to see that client’s sessions.\nClick the Sessions tab.\nClient sessions\nViewing user sessions\nProcedure\nClick Users in the menu.\nClick a user to see that user’s sessions.\nClick the Sessions tab.\nUser sessions"},
  {"id": "_revocation-policy", "title": "Revoking active sessions", "breadcrumb": ["Managing user sessions"], "url": "index.html#_revocation-policy", "md": "md/_revocation-policy.md", "text": "If your system is compromised, you can revoke all active sessions and access tokens.\nProcedure\nClick Sessions in the menu.\nFrom the Actions list, select Revocation.\nRevocation\nSpecify a time and date where sessions or tokens issued before that time and date are invalid using this console.\nClick Set to now to set the policy to the current time and date.\nClick Push to push this revocation policy to any registered OIDC client with the Keycloak OIDC client adapter."},
  {"id": "_timeouts", "title": "Session and token timeouts", "breadcrumb": ["Managing user sessions"], "url": "index.html#_timeouts", "md": "md/_timeouts.md", "text": "Keycloak includes control of the session, cookie, and token timeouts through the Sessions and Tokens tabs in the Realm settings menu.\nSessions tab\nConfiguration Description\nSSO Session Idle\nThis setting is for OIDC clients only. If a user is inactive for longer than this timeout, the user session is invalidated. This timeout value resets when clients request authentication or send a refresh token request. Keycloak adds a window of time to the idle timeout before the session invalidation takes effect. See the note later in this section.\nSSO Session Max\nThe maximum time before a user session expires.\nSSO Session Idle Remember Me\nThis setting is only available when Remember me is enabled and is similar to the standard SSO Session Idle configuration. Users can specify longer session idle timeouts when they click Remember Me when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same idle timeout as the SSO Session Idle configuration.\nSSO Session Max Remember Me\nThis setting is only available when Remember me is enabled and is similar to the standard SSO Session Max. Users can specify longer sessions when they click Remember Me when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same session lifespan as the SSO Session Max configuration.\nClient Session Idle\nIdle timeout for the client session. If the user is inactive for longer than this timeout, the client session is invalidated and the refresh token requests bump the idle timeout. This setting never affects the general SSO user session, which is unique. Note the SSO user session is the parent of zero or more client sessions, one client session is created for every different client app the user logs in. This value should specify a shorter idle timeout than the SSO Session Idle. Users can override it for individual clients in the Advanced Settings client tab. This setting is an optional configuration"},
  {"id": "_offline-access", "title": "Offline access", "breadcrumb": ["Managing user sessions"], "url": "index.html#_offline-access", "md": "md/_offline-access.md", "text": "During offline access logins, the client application requests an offline token instead of a refresh token. The client application saves this offline token and can use it for future logins if the user logs out. This action is useful if your application needs to perform offline actions on behalf of the user even when the user is not online. For example, a regular data backup.\nThe client application is responsible for persisting the offline token in storage and then using it to retrieve new access tokens from the Keycloak server.\nThe difference between a refresh token and an offline token is that an offline token never expires and is not subject to the SSO Session Idle timeout and SSO Session Max lifespan. The offline token is valid after a user logout. You must use the offline token for a refresh token action at least once per thirty days or for the value of the Offline Session Idle.\nIf you enable Offline Session Max Limited, offline tokens expire after 60 days even if you use the offline token for a refresh token action. You can change this value, Offline Session Max, in the Admin Console.\nWhen using offline access, client idle and max timeouts can be overridden at the client level. The options Client Offline Session Idle and Client Offline Session Max, in the client Advanced Settings tab, allow you to have a shorter offline timeouts for a specific application. Note that client session values also control the refresh token expiration but they never affect the global offline user SSO session. The option Client Offline Session Max is only evaluated in the client if Offline Session Max Limited is Enabled at the realm level.\nIf you enable the Revoke Refresh Token option, you can use each offline token once only. After refresh, you must store the new offline token from the refresh response instead of the previous one.\nUsers can view and revoke offline tokens that Keycloak grants them in the User Account Console. Administrators can revoke offline tokens for individual"},
  {"id": "_transient-session", "title": "Transient sessions", "breadcrumb": ["Managing user sessions"], "url": "index.html#_transient-session", "md": "md/_transient-session.md", "text": "You can conduct transient sessions in Keycloak. When using transient sessions, Keycloak does not create a user session after successful authentication. Keycloak creates a temporary, transient session for the scope of the current request that successfully authenticates the user. Keycloak can run protocol mappers using transient sessions after authentication.\nThe sid and session_state of the tokens are usually empty when the token is issued with transient sessions. So during transient sessions, the client application cannot refresh tokens or validate a specific session. Sometimes these actions are unnecessary, so you can avoid the additional resource use of persisting user sessions. This session saves performance, memory, and network communication (in cluster and cross-data center environments) resources.\nAt this moment, transient sessions are automatically used for example in the following cases:\nService account authentication with disabled token refresh. Note that token refresh is automatically disabled during service account authentication unless explicitly enabled by client switch Use refresh tokens for client credentials grant, but this client switch is deprecated and not recommended to be used.\nJWT Authorization Grant.\nSome scenarios related to Authorization Services.\nOID4VCI Pre-Authorized Code Flow."},
  {"id": "assigning-permissions-using-roles-and-groups", "title": "Assigning permissions using roles and groups", "breadcrumb": [], "url": "index.html#assigning-permissions-using-roles-and-groups", "md": "md/assigning-permissions-using-roles-and-groups.md", "text": "Roles and groups have a similar purpose, which is to give users access and permissions to use applications. Groups are a collection of users to which you apply roles and attributes. Roles define specific applications permissions and access control.\nA role typically applies to one type of user. For example, an organization may include admin, user, manager, and employee roles. An application can assign access and permissions to a role and then assign multiple users to that role so the users have the same access and permissions. For example, the Admin Console has roles that give permission to users to access different parts of the Admin Console.\nThere is a global namespace for roles and each client also has its own dedicated namespace where roles can be defined."},
  {"id": "proc-creating-realm-roles_server_administration_guide", "title": "Creating a realm role", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#proc-creating-realm-roles_server_administration_guide", "md": "md/proc-creating-realm-roles_server_administration_guide.md", "text": "Realm-level roles are a namespace for defining your roles. To see the list of roles, click Realm Roles in the menu.\nProcedure\nClick Create Role.\nEnter a Role Name.\nEnter a Description.\nClick Save.\nThe description field can be localized by specifying a substitution variable with ${var-name} strings. The localized value is configured to your theme within the themes property files. See the Server Developer Guide for more details."},
  {"id": "con-client-roles_server_administration_guide", "title": "Client roles", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#con-client-roles_server_administration_guide", "md": "md/con-client-roles_server_administration_guide.md", "text": "Client roles are namespaces dedicated to clients. Each client gets its own namespace. Client roles are managed under the Roles tab for each client. You interact with this UI the same way you do for realm-level roles."},
  {"id": "_composite-roles", "title": "Converting a role to a composite role", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#_composite-roles", "md": "md/_composite-roles.md", "text": "Any realm or client level role can become a composite role. A composite role is a role that has one or more additional roles associated with it. When a composite role is mapped to a user, the user gains the roles associated with the composite role. This inheritance is recursive so users also inherit any composite of composites. However, we recommend that composite roles are not overused.\nProcedure\nClick Realm Roles in the menu.\nClick the role that you want to convert.\nFrom the Action list, select Add associated roles.\nComposite role\nThe role selection UI is displayed on the page and you can associate realm level and client level roles to the composite role you are creating.\nIn this example, the employee realm-level role is associated with the developer composite role. Any user with the developer role also inherits the employee role.\nWhen creating tokens and SAML assertions, any composite also has its associated roles added to the claims and assertions of the authentication response sent back to the client."},
  {"id": "proc-assigning-role-mappings_server_administration_guide", "title": "Assigning role mappings", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#proc-assigning-role-mappings_server_administration_guide", "md": "md/proc-assigning-role-mappings_server_administration_guide.md", "text": "You can assign role mappings to a user through the Role Mappings tab for that user.\nProcedure\nClick Users in the menu.\nClick the user that you want to perform a role mapping on.\nClick the Role mappings tab.\nClick Assign role.\nSelect the role you want to assign to the user from the dialog.\nClick Assign.\nRole mappings\nIn the preceding example, we are assigning the composite role developer to a user. That role was created in the Composite Roles topic.\nEffective role mappings\nWhen the developer role is assigned, the employee role associated with the developer composite is displayed with Inherited \"True\". Inherited roles are the roles explicitly assigned to users and roles that are inherited from composites."},
  {"id": "_default_roles", "title": "Using default roles", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#_default_roles", "md": "md/_default_roles.md", "text": "Use default roles to automatically assign user role mappings when a user is created or imported through Identity Brokering.\nProcedure\nClick Realm settings in the menu.\nClick the User registration tab.\nDefault roles\nThis screenshot shows that some default roles already exist."},
  {"id": "_role_scope_mappings", "title": "Role scope mappings", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#_role_scope_mappings", "md": "md/_role_scope_mappings.md", "text": "On creation of an OIDC access token or SAML assertion, the user role mappings become claims within the token or assertion. Applications use these claims to make access decisions on the resources controlled by the application. Keycloak digitally signs access tokens and applications reuse them to invoke remotely secured REST services. However, these tokens have an associated risk. An attacker can obtain these tokens and use their permissions to compromise your networks. To prevent this situation, use Role Scope Mappings.\nRole Scope Mappings limit the roles declared inside an access token. When a client requests user authentication, the access token it receives contains only the role mappings that are explicitly specified for the client’s scope. The result is that the permissions of each individual access token are limited instead of giving the client access to all the user’s permissions.\nThe Full Scope Allowed switch is deprecated and will be removed in a future release. Leaving Full Scope Allowed enabled means every access token contains all roles the authenticated user holds, which unnecessarily widens the blast radius if a token is compromised. You should disable Full Scope Allowed on every client and explicitly configure the required role scope mappings instead. To enforce this automatically for all new and updated clients in a realm, configure a client policy with the Full Scope Disabled executor as described in the Enforcing Full Scope Allowed to be disabled section.\nBy default, each client gets all the role mappings of the user. You can view the role mappings for a client.\nProcedure\nClick Clients in the menu.\nClick the client to go to the details.\nClick the Client scopes tab.\nClick the link in the row with Dedicated scope and mappers for this client\nClick the Scope tab.\nFull scope\nBy default, the effective roles of scopes are every declared role in the realm. To change this default behavior, toggle Full Scope Allowed to OFF and declare the specific roles"},
  {"id": "proc-managing-groups_server_administration_guide", "title": "Groups", "breadcrumb": ["Assigning permissions using roles and groups"], "url": "index.html#proc-managing-groups_server_administration_guide", "md": "md/proc-managing-groups_server_administration_guide.md", "text": "Groups in Keycloak manage a common set of attributes and role mappings for each user. Users can be members of any number of groups and inherit the attributes and role mappings assigned to each group.\nTo manage groups, click Groups in the menu.\nGroups\nGroups are hierarchical. A group can have multiple subgroups but a group can have only one parent. Subgroups inherit the attributes and role mappings from their parent. Users inherit the attributes and role mappings from their parent as well.\nIf you have a parent group and a child group, and a user that belongs only to the child group, the user in the child group inherits the attributes and role mappings of both the parent group and the child group.\nThe hierarchy of a group is sometimes represented using the group path. The path is the complete list of names that represents the hierarchy of a specific group, from top to bottom and separated by slashes / (similar to files in a File System). For example a path can be /top/level1/level2 which means that top is a top level group and is parent of level1, which in turn is parent of level2. This path represents unambiguously the hierarchy for the group level2.\nBecause of historical reasons Keycloak, does not escape slashes in the group name itself. Therefore a group named level1/group under top uses the path /top/level1/group, which is misleading. Keycloak can be started with the option --spi-group--jpa--escape-slashes-in-group-path to true and then the slashes in the name are escaped with the character ~. The escape char marks that the slash is part of the name and has no hierarchical meaning. The previous path example would be /top/level1~/group when escaped.\nbin/kc.[sh|bat] start --spi-group--jpa--escape-slashes-in-group-path=true\nThe following example includes a top-level Sales group and a child North America subgroup.\nTo add a group:\nClick the group.\nClick Create group.\nEnter a group name.\nClick Create.\nClick the group name.\nThe group management page is displayed.\nGroup"},
  {"id": "configuring-authentication_server_administration_guide", "title": "Configuring authentication", "breadcrumb": [], "url": "index.html#configuring-authentication_server_administration_guide", "md": "md/configuring-authentication_server_administration_guide.md", "text": "This chapter covers several authentication topics. These topics include:\nEnforcing strict password and One Time Password (OTP) policies.\nManaging different credential types.\nLogging in with Kerberos.\nDisabling and enabling built-in credential types."},
  {"id": "_password-policies", "title": "Password policies", "breadcrumb": ["Configuring authentication"], "url": "index.html#_password-policies", "md": "md/_password-policies.md", "text": "When Keycloak creates a realm, it does not associate password policies with the realm. You can set a simple password with no restrictions on its length, security, or complexity. Simple passwords are unacceptable in production environments. Keycloak has a set of password policies available through the Admin Console.\nProcedure\nClick Authentication in the menu.\nClick the Policies tab.\nSelect the policy to add in the Add policy drop-down box.\nEnter a value that applies to the policy chosen.\nClick Save.\nPassword policy\nAfter saving the policy, Keycloak enforces the policy for new users.\nThe new policy will not be effective for existing users. Therefore, make sure that you set the password policy from the beginning of the realm creation or add \"Update password\" to existing users or use \"Expire password\" to make sure that users update their passwords in next \"N\" days, which will actually adjust to new password policies.\nPassword policy types\nHashAlgorithm\nPasswords are not stored in cleartext. Before storage or validation, Keycloak hashes passwords using standard hashing algorithms.\nSupported password hashing algorithms are shown in the following table.\nHashing algorithm Description\nargon2\nArgon2 (default for non-FIPS deployments)\npbkdf2-sha512\nPBKDF2 with SHA512 (default for FIPS deployments)\npbkdf2-sha256\nPBKDF2 with SHA256\npbkdf2\nPBKDF2 with SHA1 (deprecated)\nIt is highly recommended to use Argon2 when possible as it has significantly less CPU requirements compared to PBKDF2, while at the same time being more secure.\nThe default password hashing algorithm for the server can be configured with --spi-password-hashing--provider-default=<algorithm>.\nTo prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM. To configure the Argon2 hashing provider, use its provider options.\nSee the Server Developer Guide on how to add your own hashing algorithm.\nIf you change the hashing"},
  {"id": "one-time-password-otp-policies", "title": "One Time Password (OTP) policies", "breadcrumb": ["Configuring authentication"], "url": "index.html#one-time-password-otp-policies", "md": "md/one-time-password-otp-policies.md", "text": "Keycloak has several policies for setting up a FreeOTP or Google Authenticator One-Time Password generator.\nProcedure\nClick Authentication in the menu.\nClick the Policy tab.\nClick the OTP Policy tab.\nOtp Policy\nKeycloak generates a QR code on the OTP set-up page, based on information configured in the OTP Policy tab. FreeOTP and Google Authenticator scan the QR code when configuring OTP.\nTime-based or counter-based one time passwords\nThe algorithms available in Keycloak for your OTP generators are time-based and counter-based.\nWith Time-Based One Time Passwords (TOTP), the token generator will hash the current time and a shared secret. The server validates the OTP by comparing the hashes within a window of time to the submitted value. TOTPs are valid for a short window of time.\nWith Counter-Based One Time Passwords (HOTP), Keycloak uses a shared counter rather than the current time. The Keycloak server increments the counter with each successful OTP login. Valid OTPs change after a successful login.\nTOTP is more secure than HOTP because the matchable OTP is valid for a short window of time, while the OTP for HOTP is valid for an indeterminate amount of time. HOTP is more user-friendly than TOTP because no time limit exists to enter the OTP.\nHOTP requires a database update every time the server increments the counter. This update is a performance drain on the authentication server during heavy load. To increase efficiency, TOTP does not remember passwords used, so there is no need to perform database updates. The drawback is that it is possible to reuse TOTPs in the valid time interval.\nTOTP configuration options\nOTP hash algorithm\nThe default algorithm is SHA1. The other, more secure options are SHA256 and SHA512.\nNumber of digits\nThe length of the OTP. Short OTPs are user-friendly, easier to type, and easier to remember. Longer OTPs are more secure than shorter OTPs.\nLook around window\nThe number of intervals the server attempts to match the hash. This option is"},
  {"id": "_authentication-flows", "title": "Authentication flows", "breadcrumb": ["Configuring authentication"], "url": "index.html#_authentication-flows", "md": "md/_authentication-flows.md", "text": "An authentication flow is a container of authentications, screens, and actions, during log in, registration, and other Keycloak workflows.\nBuilt-in flows\nKeycloak has several built-in flows. You cannot modify these flows, but you can alter the flow’s requirements to suit your needs.\nProcedure\nClick Authentication in the menu.\nClick on the Browser item in the list to see the details.\nBrowser flow\nAuth type\nThe name of the authentication or the action to execute. If an authentication is indented, it is in a sub-flow. It may or may not be executed, depending on the behavior of its parent.\nCookie\nThe first time a user logs in successfully, Keycloak sets a session cookie. If the cookie is already set, this authentication type is successful. Since the cookie provider returned success and each execution at this level of the flow is alternative, Keycloak does not perform any other execution. This results in a successful login.\nKerberos\nThis authenticator is disabled by default and is skipped during the Browser Flow.\nIdentity Provider Redirector\nThis action is configured through the Actions > Config link. It redirects to another IdP for identity brokering.\nForms\nSince this sub-flow is marked as alternative, it will not be executed if the Cookie authentication type passed. This sub-flow contains an additional authentication type that needs to be executed. Keycloak loads the executions for this sub-flow and processes them.\nThe first execution is the Username Password Form, an authentication type that renders the username and password page. It is marked as required, so the user must enter a valid username and password.\nThe second execution is the Browser - Conditional 2FA sub-flow. This sub-flow is conditional and executes depending on the result of the Condition - User Configured and Condition - credential execution. If the result is true, Keycloak loads the executions for this sub-flow and processes them.\nThe next execution is the Condition - User Configured authentication."},
  {"id": "_user_session_limits", "title": "User session limits", "breadcrumb": ["Configuring authentication"], "url": "index.html#_user_session_limits", "md": "md/_user_session_limits.md", "text": "Limits on the number of session that a user can have can be configured. Sessions can be limited per realm or per client.\nTo add session limits to a flow, perform the following steps.\nClick Add step for the flow.\nSelect User session count limiter from the item list.\nClick Add.\nClick Required for the User Session Count Limiter authentication type to set its requirement to required.\nClick ⚙️ (gear icon) for the User Session Count Limiter.\nEnter an alias for this config.\nEnter the required maximum number of sessions that a user can have in this realm. For example, if 2 is the value, 2 SSO sessions is the maximum that each user can have in this realm. If 0 is the value, this check is disabled.\nEnter the required maximum number of sessions a user can have for the client. For example, if 2 is the value, then 2 SSO sessions is the maximum in this realm for each client. So when a user is trying to authenticate to client foo, but that user has already authenticated in 2 SSO sessions to client foo, either the authentication will be denied or an existing sessions will be killed based on the behavior configured. If a value of 0 is used, this check is disabled. If both session limits and client session limits are enabled, it makes sense to have client session limits to be always lower than session limits. The limit per client can never exceed the limit of all SSO sessions of this user.\nSelect the behavior that is required when the user tries to create a session after the limit is reached. Available behaviors are:\nDeny new session - when a new session is requested and the session limit is reached, no new sessions can be created.\nTerminate oldest session - when a new session is requested and the session limit has been reached, the oldest session will be removed and the new session created.\nOptionally, add a custom error message to be displayed when the limit is reached.\nNote that the user session limits should be added to your bound Browser flow, Direct grant flow, Reset"},
  {"id": "script-authenticator", "title": "Script Authenticator", "breadcrumb": ["Configuring authentication"], "url": "index.html#script-authenticator", "md": "md/script-authenticator.md", "text": "Ability to upload scripts through the Admin Console and REST endpoints is deprecated.\nFor more details see JavaScript Providers."},
  {"id": "_kerberos", "title": "Kerberos", "breadcrumb": ["Configuring authentication"], "url": "index.html#_kerberos", "md": "md/_kerberos.md", "text": "Keycloak supports login with a Kerberos ticket through the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) protocol. SPNEGO authenticates transparently through the web browser after the user authenticates the session. For non-web cases, or when a ticket is not available during login, Keycloak supports login with Kerberos username and password.\nA typical use case for web authentication is the following:\nThe user logs into the desktop.\nThe user accesses a web application secured by Keycloak using a browser.\nThe application redirects to Keycloak login.\nKeycloak renders the HTML login screen with status 401 and HTTP header WWW-Authenticate: Negotiate\nIf the browser has a Kerberos ticket from desktop login, the browser transfers the desktop sign-on information to Keycloak in header Authorization: Negotiate 'spnego-token'. Otherwise, it displays the standard login screen, and the user enters the login credentials.\nKeycloak validates the token from the browser and authenticates the user.\nIf using LDAPFederationProvider with Kerberos authentication support, Keycloak provisions user data from LDAP. If using KerberosFederationProvider, Keycloak lets the user update the profile and pre-fill login data.\nKeycloak returns to the application. Keycloak and the application communicate through OpenID Connect or SAML messages. Keycloak acts as a broker to Kerberos/SPNEGO login. Therefore Keycloak authenticating through Kerberos is hidden from the application.\nThe Negotiate www-authenticate scheme allows NTLM as a fallback to Kerberos and on some web browsers in Windows NTLM is supported by default. If a www-authenticate challenge comes from a server outside a browsers permitted list, users may encounter an NTLM dialog prompt. A user would need to click the cancel button on the dialog to continue as Keycloak does not support this mechanism. This situation can happen if Intranet web browsers are not strictly configured or if Keycloak serves users in both the Intranet and"},
  {"id": "_x509", "title": "X.509 client certificate user authentication", "breadcrumb": ["Configuring authentication"], "url": "index.html#_x509", "md": "md/_x509.md", "text": "Keycloak supports logging in with an X.509 client certificate if you have configured the server to use mutual SSL authentication.\nA typical workflow:\nA client sends an authentication request over SSL/TLS channel.\nDuring the SSL/TLS handshake, the server and the client exchange their x.509/v3 certificates.\nThe container (WildFly) validates the certificate PKIX path and the certificate expiration date.\nThe x.509 client certificate authenticator validates the client certificate by using the following methods:\nChecks the certificate revocation status by using CRL or CRL Distribution Points.\nChecks the Certificate revocation status by using OCSP (Online Certificate Status Protocol).\nValidates whether the key in the certificate matches the expected key.\nValidates whether the extended key in the certificate matches the expected extended key.\nIf any of the these checks fail, the x.509 authentication fails. Otherwise, the authenticator extracts the certificate identity and maps it to an existing user.\nWhen the certificate maps to an existing user, the behavior diverges depending on the authentication flow:\nIn the Browser Flow, the server prompts users to confirm their identity or sign in with a username and password.\nIn the Direct Grant Flow, the server signs in the user.\nNote that it is the responsibility of the web container to validate certificate PKIX path. X.509 authenticator on the Keycloak side provides just the additional support for check the certificate expiration, certificate revocation status and key usage. If you are using Keycloak deployed behind reverse proxy, make sure that your reverse proxy is configured to validate PKIX path. If you do not use reverse proxy and users directly access the WildFly, you should be fine as WildFly makes sure that PKIX path is validated as long as it is configured as described below.\nFeatures\nSupported Certificate Identity Sources:\nMatch SubjectDN by using regular expressions\nX500 Subject’s email attribute\nX500 Subject’s"},
  {"id": "webauthn_server_administration_guide", "title": "W3C Web Authentication (WebAuthn)", "breadcrumb": ["Configuring authentication"], "url": "index.html#webauthn_server_administration_guide", "md": "md/webauthn_server_administration_guide.md", "text": "Keycloak provides support for W3C Web Authentication (WebAuthn). Keycloak works as a WebAuthn’s Relying Party (RP).\nWebAuthn’s operations success depends on the user’s WebAuthn supporting authenticator, browser, and platform. Make sure your authenticator, browser, and platform support the WebAuthn specification.\nWebAuthn’s specification uses a user.id to map a public key credential to a specific user account in the Relying Party. This user ID handle is an opaque byte sequence with a maximum size of 64 bytes. Keycloak passes the internal database ID to the registration, which in common users is an UUID of 36 characters. But, if the user is from a external user federation provider, the internal Keycloak ID is an storage ID in the form f:<provider-id>:<user-id> that can exceed the 64 byte limitation. Please take this into account and use short IDs for the federation provider component and for the users coming from that provider when combining the Storage SPI and WebAuthn.\nSetup\nThe setup procedure of WebAuthn support for 2FA is the following:\nCheck WebAuthn authenticator registration is enabled\nClick Authentication in the menu.\nClick the Required Actions tab.\nCheck action Webauthn Register switch is set to ON.\nToggle the Default Action switch to ON if you want all new users to be required to register their WebAuthn credentials.\nEnable WebAuthn authentication in the default browser flow\nClick Authentication in the menu.\nClick the Browser flow.\nLocate the execution WebAuthn Authenticator inside the Browser - Conditional 2FA sub-flow.\nChange the requirement from Disabled to Alternative for that execution.\nWebAuthn browser flow conditional with OTP\nWith this configuration, the users can choose between using WebAuthn and OTP for the second factor. As the sub-flow is conditional, they are only asked to present a 2FA credential (OTP or WebAuthn) if they have already registered one of the respective credential types. If a user has configured both credential types, the"},
  {"id": "passkeys_server_administration_guide", "title": "Passkeys", "breadcrumb": ["Configuring authentication"], "url": "index.html#passkeys_server_administration_guide", "md": "md/passkeys_server_administration_guide.md", "text": "Keycloak provides support for Passkeys. Keycloak works as a Passkeys Relying Party (RP).\nPasskey registration and authentication are performed using the same features of WebAuthn. More specifically Passkeys are related to LoginLess WebAuthn as they try to avoid any password during login. Therefore, users of Keycloak can do Passkey registration and authentication by existing WebAuthn registration and authentication, using the passwordless variants.\nThe Passkeys feature has been integrated seamlessly in the default authentication forms in two different ways. When activated, both conditional UI and modal UI are available in the forms in which the username input is displayed (for example Username Password Form or Username Form). The exact behavior on page load — whether a passkey selection dialog appears automatically or credentials are offered only through browser autofill — is controlled by the Passkey Mediation setting in the WebAuthn Passwordless Policy.\nBesides, the password forms, when the username was already selected, always show the modal UI button to login by passkey if the current user has passwordless WebAuthn credentials associated. This way modal and conditional UI can be used to perform a complete login from scratch that needs username and password, and only modal UI is presented when the username is already selected in the authentication process (because of re-authentication or because the user was selected before in the process not using a passkey).\nPasskeys have been added to the following authenticator implementations:\nUsername Password Form: The username and password form used by default in Keycloak.\nUsername Form: The form in which the username is displayed alone and is typically followed by the password form. This authenticator is used when the username and password fields want to be presented to the user in two different steps.\nPassword Form: Authenticating using Passkeys in the Username Form skips the next Password Form execution. The"},
  {"id": "conditions-in-conditional-flows", "title": "Conditions in conditional flows", "breadcrumb": ["Configuring authentication"], "url": "index.html#conditions-in-conditional-flows", "md": "md/conditions-in-conditional-flows.md", "text": "As was mentioned in Execution requirements, Condition executions can be only contained in Conditional subflow. If all Condition executions evaluate as true, then the Conditional sub-flow acts as Required. You can process the next execution in the Conditional sub-flow. If some executions included in the Conditional sub-flow evaluate as false, then the whole sub-flow is considered as Disabled.\nAvailable conditions\nCondition - User Role\nThis execution has the ability to determine if the user has a role defined by User role field. If the user has the required role, the execution is considered as true and other executions are evaluated. The administrator has to define the following fields:\nAlias\nDescribes a name of the execution, which will be shown in the authentication flow.\nUser role\nRole the user should have to execute this flow. To specify an application role the syntax is appname.approle (for example myapp.myrole).\nCondition - User Configured\nThis checks if the other executions in the flow are configured for the user. The Execution requirements section includes an example of the OTP form.\nCondition - User Attribute\nThis checks if the user has set up the required attribute: optionally, the check can also evaluate the group attributes. There is a possibility to negate output, which means the user should not have the attribute. The User Attributes section shows how to add a custom attribute. You can provide these fields:\nAlias\nDescribes a name of the execution, which will be shown in the authentication flow.\nAttribute name\nName of the attribute to check.\nExpected attribute value\nExpected value in the attribute.\nInclude group attributes\nIf On, the condition checks if any of the joined group has one attribute matching the configured name and value: this option can affect performance\nNegate output\nYou can negate the output. In other words, the attribute should not be present.\nCondition - sub-flow executed\nThe condition checks if a previous sub-flow was successfully"},
  {"id": "_authentication-sessions", "title": "Authentication sessions", "breadcrumb": ["Configuring authentication"], "url": "index.html#_authentication-sessions", "md": "md/_authentication-sessions.md", "text": "When a login page is opened for the first time in a web browser, Keycloak creates an object called authentication session that stores some useful information about the request. Whenever a new login page is opened from a different tab in the same browser, Keycloak creates a new record called authentication sub-session that is stored within the authentication session. Authentication requests can come from any type of clients such as the Admin CLI. In that case, a new authentication session is also created with one authentication sub-session. Please note that authentication sessions can be created also in other ways than using a browser flow.\nThe authentication session usually expires after 30 minutes by default. The exact time is specified by the Login timeout switch in the Sessions tab of the admin console when configuring realms.\nAuthentication in more browser tabs\nAs described in the previous section, a situation can involve a user who is trying to authenticate to the Keycloak server from multiple tabs of a single browser. However, when that user authenticates in one browser tab, the other browser tabs will automatically restart the authentication. This authentication occurs due to the small javascript available on the Keycloak login pages. The restart will typically authenticate the user in other browser tabs and redirect to clients because there is an SSO session now due to the fact that the user just successfully authenticated in first browser tab. Some rare exceptions exist when a user is not automatically authenticated in other browser tabs, such as for instance when using an OIDC parameter prompt=login or step-up authentication requesting a stronger authentication factor than the currently authenticated factor.\nIn some rare cases, it can happen that after authentication in the first browser tab, other browser tabs are not able to restart authentication because the authentication session is already expired. In this case, the particular browser tab will"},
  {"id": "_identity_broker", "title": "Integrating identity providers", "breadcrumb": [], "url": "index.html#_identity_broker", "md": "md/_identity_broker.md", "text": "An Identity Broker is an intermediary service connecting service providers with identity providers. The identity broker creates a relationship with an external identity provider to use the provider’s identities to access the internal services the service provider exposes.\nFrom a user perspective, identity brokers provide a user-centric, centralized way to manage identities for security domains and realms. You can link an account with one or more identities from identity providers or create an account based on the identity information from them.\nAn identity provider derives from a specific protocol used to authenticate and send authentication and authorization information to users. It can be:\nA social provider such as Facebook, Google, or Twitter.\nA business partner whose users need to access your services.\nA cloud-based identity service you want to integrate.\nTypically, Keycloak bases identity providers on the following protocols:\nSAML v2.0\nOpenID Connect v1.0\nOAuth v2.0"},
  {"id": "_identity_broker_overview", "title": "Brokering overview", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_overview", "md": "md/_identity_broker_overview.md", "text": "When using Keycloak as an identity broker, Keycloak does not force users to provide their credentials to authenticate in a specific realm. Keycloak displays a list of identity providers from which they can authenticate.\nIf you configure a default identity provider, Keycloak redirects users to the default provider.\nDifferent protocols may require different authentication flows. All the identity providers supported by Keycloak use the following flow.\nIdentity broker flow\nThe unauthenticated user requests a protected resource in a client application.\nThe client application redirects the user to Keycloak to authenticate.\nKeycloak displays the login page with a list of identity providers configured in a realm.\nThe user selects one of the identity providers by clicking its button or link.\nKeycloak issues an authentication request to the target identity provider requesting authentication and redirects the user to the identity provider’s login page. The administrator has already set the connection properties and other configuration options for the Admin Console’s identity provider.\nThe user provides credentials or consents to authenticate with the identity provider.\nUpon successful authentication by the identity provider, the user redirects back to Keycloak with an authentication response. Usually, the response contains a security token used by Keycloak to trust the identity provider’s authentication and retrieve user information.\nKeycloak checks if the response from the identity provider is valid. If valid, Keycloak imports and creates a user if the user does not already exist. Keycloak may ask the identity provider for further user information if the token does not contain that information. This behavior is identity federation. If the user already exists, Keycloak may ask the user to link the identity returned from the identity provider with the existing account. This behavior is account linking. With Keycloak, you can configure Account linking and specify it in the"},
  {"id": "default_identity_provider", "title": "Default Identity Provider", "breadcrumb": ["Integrating identity providers"], "url": "index.html#default_identity_provider", "md": "md/default_identity_provider.md", "text": "Keycloak can redirect to an identity provider rather than displaying the login form. To enable this redirection:\nProcedure\nClick Authentication in the menu.\nClick the Browser flow.\nClick the gear icon ⚙️ on the Identity Provider Redirector row.\nSet Default Identity Provider to the identity provider you want to redirect users to.\nIf Keycloak does not find the configured default identity provider, the login form is displayed.\nThis authenticator is responsible for processing the kc_idp_hint query parameter. See the client suggested identity provider section for more information.\nThe authenticator will redirect to the identity provider and authentication is delegated to the identity provider. The browser authentication flow will not continue after the login with the identity provider is successfully finished. If you want to perform additional steps after the identity provider login (for example 2-factor authentication), it may be needed to configure Post login flow."},
  {"id": "_general-idp-config", "title": "General configuration", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_general-idp-config", "md": "md/_general-idp-config.md", "text": "The foundations of the identity broker configuration are identity providers (IDPs). Keycloak creates identity providers for each realm and enables them for every application by default. Users from a realm can use any of the registered identity providers when signing in to an application.\nProcedure\nClick Identity Providers in the menu.\nIdentity Providers\nSelect an identity provider. Keycloak displays the configuration page for the identity provider you selected.\nAdd Facebook identity Provider\nWhen you configure an identity provider, the identity provider appears on the Keycloak login page as an option. You can place custom icons on the login screen for each identity provider. See custom icons for more information.\nIDP login page\nSocial\nSocial providers enable social authentication in your realm. With Keycloak, users can log in to your application using a social network account. Supported providers include Twitter, Facebook, Google, LinkedIn, Instagram, Microsoft, PayPal, Openshift v4, GitHub, GitLab, Bitbucket, and Stack Overflow.\nProtocol-based\nProtocol-based providers rely on specific protocols to authenticate and authorize users. Using these providers, you can connect to any identity provider compliant with a specific protocol. Keycloak provides support for SAML v2.0 and OpenID Connect v1.0 protocols. You can configure and broker any identity provider based on these open standards.\nAlthough each type of identity provider has its configuration options, all share a common configuration. The following configuration options available:\nTable 2. Common Configuration\nConfiguration Description\nAlias\nThe alias is a unique identifier for an identity provider and references an internal identity provider. Keycloak uses the alias to build redirect URIs for OpenID Connect protocols that require a redirect URI or callback URL to communicate with an identity provider. All identity providers must have an alias. Alias examples include facebook, google, and idp.acme.com.\nEnabled"},
  {"id": "social-identity-providers", "title": "Social Identity Providers", "breadcrumb": ["Integrating identity providers"], "url": "index.html#social-identity-providers", "md": "md/social-identity-providers.md", "text": "A social identity provider can delegate authentication to a trusted, respected social media account. Keycloak includes support for social networks such as Google, Facebook, Twitter, GitHub, LinkedIn, Microsoft, and Stack Overflow.\nBitbucket\nTo log in with Bitbucket, perform the following procedure.\nProcedure\nClick Identity Providers in the menu.\nFrom the Add provider list, select Bitbucket.\nAdd identity provider\nCopy the value of Redirect URI to your clipboard.\nIn a separate browser tab, perform the OAuth on Bitbucket Cloud process. When you click Add Consumer:\nPaste the value of Redirect URI into the Callback URL field.\nEnsure you select Email and Read in the Account section to permit your application to read email.\nNote the Key and Secret values Bitbucket displays when you create your consumer.\nIn Keycloak, paste the value of the Key into the Client ID field.\nIn Keycloak, paste the value of the Secret into the Client Secret field.\nClick Add.\nFacebook\nProcedure\nClick Identity Providers in the menu.\nFrom the Add provider list, select Facebook.\nAdd identity provider\nCopy the value of Redirect URI to your clipboard.\nIn a separate browser tab, open the Meta for Developers.\nClick My Apps.\nSelect Create App.\nAdd a use case\nSelect Other.\nSelect an app type\nSelect Consumer.\nCreate an app\nFill in all required fields.\nClick Create app. Meta then brings you to the dashboard.\nAdd a product\nClick Set Up in the Facebook Login box.\nSelect Web.\nEnter the Redirect URI’s value into the Site URL field and click Save.\nIn the navigation panel, select App settings - Basic.\nClick Show in the App Secret field.\nNote the App ID and the App Secret.\nEnter the App ID and App Secret values from your Facebook app into the Client ID and Client Secret fields in Keycloak.\nClick Add\nEnter the required scopes into the Default Scopes field. By default, Keycloak uses the email scope. See Graph API for more information about Facebook scopes.\nKeycloak sends profile requests to"},
  {"id": "_identity_broker_oidc", "title": "OpenID Connect v1.0 identity providers", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_oidc", "md": "md/_identity_broker_oidc.md", "text": "Keycloak brokers identity providers based on the OpenID Connect protocol. These identity providers (IDPs) must support the Authorization Code Flow defined in the specification to authenticate users and authorize access.\nProcedure\nClick Identity Providers in the menu.\nFrom the Add provider list, select OpenID Connect v1.0.\nAdd identity provider\nEnter your initial configuration options. See General IDP Configuration for more information about configuration options.\nTable 3. OpenID connect config\nConfiguration Description\nAuthorization URL\nThe authorization URL endpoint the OIDC protocol requires.\nToken URL\nThe token URL endpoint the OIDC protocol requires.\nLogout URL\nThe logout URL endpoint in the OIDC protocol. This value is optional.\nBackchannel Logout\nA background, out-of-band, REST request to the IDP to log out the user. Some IDPs perform logout through browser redirects only, as they may identify sessions using a browser cookie.\nUser Info URL\nAn endpoint the OIDC protocol defines. This endpoint points to user profile information.\nClient Authentication\nDefines the Client Authentication method Keycloak uses with the Authorization Code Flow. In the case of JWT signed with a private key, Keycloak uses the realm private key. In the other cases, define a client secret. See the Client Authentication specifications for more information.\nClient ID\nA realm acting as an OIDC client to the external IDP. The realm must have an OIDC client ID if you use the Authorization Code Flow to interact with the external IDP.\nClient Secret\nClient secret from an external vault. This secret is necessary if you are using the Authorization Code Flow.\nClient Assertion Signature Algorithm\nSignature algorithm to create JWT assertion as client authentication. In the case of JWT signed with private key or Client secret as jwt, it is required. If no algorithm is specified, the following algorithm is adapted. RS256 is adapted in the case of JWT signed with private key. HS256 is adapted in the case"},
  {"id": "_identity_broker_oauth", "title": "OAuth v2 identity providers", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_oauth", "md": "md/_identity_broker_oauth.md", "text": "Keycloak brokers identity providers based on the OAuth v2 protocol. These identity providers (IDPs) must support the Authorization Code Flow defined in the specification to authenticate users and authorize access.\nProcedure\nClick Identity Providers in the menu.\nFrom the Add provider list, select OAuth v2.\nEnter your initial configuration options. See General IDP Configuration for more information about configuration options.\nTable 4. OAuth2 settings\nConfiguration Description\nAuthorization URL\nThe authorization URL endpoint.\nToken URL\nThe token URL endpoint.\nUser Info URL\nAn endpoint from where information about the user will be fetched from. When invoking this endpoint, Keycloak will send the request with the access token issued by the identity provider as a bearer token. As a result, it expects the response to be a JSON document with the claims that should be used to obtain user profile information like ID, username, email, and first and last names.\nClient Authentication\nDefines the Client Authentication method Keycloak uses with the Authorization Code Flow. In the case of JWT signed with a private key, Keycloak uses the realm private key. In the other cases, define a client secret. See the Client Authentication specifications for more information.\nClient ID\nA realm acting as an OIDC client to the external IDP. The realm must have an OIDC client ID if you use the Authorization Code Flow to interact with the external IDP.\nClient Secret\nClient secret from an external vault. This secret is necessary if you are using the Authorization Code Flow.\nClient Assertion Signature Algorithm\nSignature algorithm to create JWT assertion as client authentication. In the case of JWT signed with private key or Client secret as jwt, it is required. If no algorithm is specified, the following algorithm is adapted. RS256 is adapted in the case of JWT signed with private key. HS256 is adapted in the case of Client secret as jwt.\nClient Assertion Audience\nThe audience to use for the"},
  {"id": "saml-v2-0-identity-providers", "title": "SAML v2.0 Identity Providers", "breadcrumb": ["Integrating identity providers"], "url": "index.html#saml-v2-0-identity-providers", "md": "md/saml-v2-0-identity-providers.md", "text": "Keycloak can broker identity providers based on the SAML v2.0 protocol.\nProcedure\nClick Identity Providers in the menu.\nFrom the Add provider list, select SAML v2.0.\nAdd identity provider\nEnter your initial configuration options. See General IDP Configuration for more information about configuration options.\nTable 6. SAML Config\nConfiguration Description\nService Provider Entity ID\nThe SAML Entity ID that the remote Identity Provider uses to identify requests from this Service Provider. By default, this setting is set to the realms base URL <root>/realms/{realm-name}.\nIdentity Provider Entity ID\nThe Entity ID used to validate the Issuer for received SAML assertions. If empty, no Issuer validation is performed.\nSingle Sign-On Service URL\nThe SAML endpoint that starts the authentication process. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.\nArtifact service URL\nThe SAML artifact resolution endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.\nSingle Logout Service URL\nThe SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.\nBackchannel Logout\nToggle this switch to ON if your SAML IDP supports back channel logout.\nNameID Policy Format\nThe URI reference corresponding to a name identifier format. By default, Keycloak sets it to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.\nPrincipal Type\nSpecifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' NameID Policy Format value.\nPrincipal Attribute\nIf a Principal type is non-blank, this field specifies the name (\"Attribute [Name]\") or the friendly name (\"Attribute [Friendly Name]\") of the identifying attribute.\nAllow create"},
  {"id": "_identity_broker_spiffe", "title": "SPIFFE identity providers", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_spiffe", "md": "md/_identity_broker_spiffe.md", "text": "SPIFFE is Preview and is not fully supported. This feature is disabled by default.\nTo enable start the server with --features=preview or --features=spiffe\nA SPIFFE identity provider supports authenticating clients with SPIFFE JWT SVIDs.\nEach client must have a unique subject identifier (SPIFFE ID) for each realm.\nSPIFFE JWT SVIDs can be re-used multiple times. As a security best practice, reduce the expiration time and make sure tokens can not be intercepted in communication between the client and Keycloak.\nProcedure\nClick Identity Providers in the menu.\nFrom the Add provider list, select SPIFFE.\nAdd SPIFFE provider\nEnter your initial configuration options.\nTable 8. SPIFFE settings\nConfiguration Description\nAlias\nThe alias for the identity provider is used to link a client to the provider\nSPIFFE Trust Domain\nThe SPIFFE Trust domain (for example spiffe://my-trust-domain)\nSPIFFE Bundle Endpoint\nhttps URL for the SPIFFE Bundle Endpoint or the OpenID Connect JWKS endpoint where the SPIFFE servers public keys are exposed"},
  {"id": "_identity_broker_kubernetes", "title": "Kubernetes identity providers", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_kubernetes", "md": "md/_identity_broker_kubernetes.md", "text": "A Kubernetes identity provider supports authenticating clients with Kubernetes service account tokens.\nThis feature can be enabled and disabled with the feature kubernetes-service-accounts which is enabled by default. It depends on the feature client-auth-federated which is enabled by default as well.\nThe default issuer URL for a Kubernetes cluster is https://kubernetes.default.svc.cluster.local. You can discover this value by decoding a service account token to retrieve the value of the iss claim. For managed Kubernetes clusters where service account tokens use an external issuer, leave the issuer URL empty and provide the Kubernetes API server or another OIDC discovery URL instead. When the identity provider is saved, Keycloak resolves and persists the issuer URL and JWKS URL from the discovery document. When the provider is updated with a discovery URL, Keycloak resolves the discovery document again and updates the persisted values.\nWhen an issuer discovery URL is configured, Keycloak invokes its <DISCOVERY_URL>/.well-known/openid-configuration endpoint when the provider is saved or updated and persists the returned JWKS URL. Otherwise, it discovers keys from <ISSUER>/.well-known/openid-configuration when needed. Keycloak uses the token from /var/run/secrets/kubernetes.io/serviceaccount/token to access the in-cluster discovery endpoint. When loading JWKS, it uses the token when its iss claim matches the configured issuer.\nEach identity provider must have a unique issuer. Each client must also have a unique subject identifier for each issuer. As the subject identifier is built from the namespace and service account name, each client must have its own service account if multiple clients share a namespace.\nAs a security best practice, do not use the default service account in a namespace, as it is shared with all Pods in a namespace. Instead, create an individual service account for each client.\nKubernetes service account tokens can be reused multiple times. As a"},
  {"id": "_client_suggested_idp", "title": "Client-suggested Identity Provider", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_client_suggested_idp", "md": "md/_client_suggested_idp.md", "text": "OIDC applications can bypass the Keycloak login page by hinting at the identity provider they want to use. You can enable this by setting the kc_idp_hint query parameter in the Authorization Code Flow authorization endpoint.\nWith Keycloak OIDC client adapters, you can specify this query parameter when you access a secured resource in the application.\nFor example:\nGET /myapplication.com?kc_idp_hint=facebook HTTP/1.1\nHost: localhost:8080\nIn this case, your realm must have an identity provider with a facebook alias. If this provider does not exist, the login form is displayed.\nIf you are using the JavaScript adapter, you can also achieve the same behavior as follows:\nconst keycloak = new Keycloak({\n\turl: \"http://keycloak-server\",\n\trealm: \"my-realm\",\n\tclientId: \"my-app\"\n);\n\nawait keycloak.createLoginUrl({\n\tidpHint: 'facebook'\n});\nWith the kc_idp_hint query parameter, the client can override the default identity provider if you configure one for the Identity Provider Redirector authenticator. The client can disable the automatic redirecting by setting the kc_idp_hint query parameter to an empty value."},
  {"id": "_mappers", "title": "Mapping claims and assertions", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_mappers", "md": "md/_mappers.md", "text": "You can import the SAML and OpenID Connect metadata, provided by the external IDP you are authenticating with, into the realm. After importing, you can extract user profile metadata and other information, so you can make it available to your applications.\nEach user logging into your realm using an external identity provider has an entry in the local Keycloak database, based on the metadata from the SAML or OIDC assertions and claims.\nProcedure\nClick Identity Providers in the menu.\nSelect one of the identity providers in the list.\nClick the Mappers tab.\nIdentity provider mappers\nClick Add mapper.\nIdentity provider mapper\nSelect a value for Sync Mode Override. The mapper updates user information when users log in repeatedly according to this setting.\nSelect legacy to use the behavior of the previous Keycloak version.\nSelect import to import data from when the user was first created in Keycloak during the first login to Keycloak with a particular identity provider.\nSelect force to update user data at each user login.\nSelect inherit to use the sync mode configured in the identity provider. All other options will override this sync mode.\nSelect a mapper from the Mapper Type list. Hover over the Mapper Type for a description of the mapper and configuration to enter for the mapper.\nClick Save.\nFor JSON-based claims, you can use dot notation for nesting and square brackets to access array fields by index. For example, contact.address[0].country.\nTo investigate the structure of user profile JSON data provided by social providers, you can enable the DEBUG level logger org.keycloak.social.user_profile_dump when starting the server."},
  {"id": "available-user-session-data", "title": "Available user session data", "breadcrumb": ["Integrating identity providers"], "url": "index.html#available-user-session-data", "md": "md/available-user-session-data.md", "text": "After a user login from an external IDP, Keycloak stores user session note data that you can access. This data can be propagated to the client requesting log in using the token or SAML assertion passed back to the client using an appropriate client mapper.\nidentity_provider\nThe IDP alias of the broker used to perform the login.\nidentity_provider_identity\nThe IDP username of the currently authenticated user. Often, but not always, the same as the Keycloak username. For example, Keycloak can link a user john` to a Facebook user john123@gmail.com. In that case, the value of the user session note is john123@gmail.com.\nYou can use a Protocol Mapper of type User Session Note to propagate this information to your clients."},
  {"id": "_identity_broker_first_login", "title": "First login flow", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_first_login", "md": "md/_identity_broker_first_login.md", "text": "When users log in through identity brokering, Keycloak imports and links aspects of the user within the realm’s local database. When Keycloak successfully authenticates users through an external identity provider, two situations can exist:\nKeycloak has already imported and linked a user account with the authenticated identity provider account. In this case, Keycloak authenticates as the existing user and redirects back to the application.\nNo account exists for this user in Keycloak. Usually, you register and import a new account into the Keycloak database, but there may be an existing Keycloak account with the same email address. Automatically linking the existing local account to the external identity provider is a potential security hole. You cannot always trust the information you get from the external identity provider.\nDifferent organizations have different requirements when dealing with some of these situations. With Keycloak, you can use the First Login Flow option in the IDP settings to choose a workflow for a user logging in from an external IDP for the first time. By default, the First Login Flow option points to the first broker login flow, but you can use your flow or different flows for different identity providers.\nThe flow is in the Admin Console under the Authentication tab. When you choose the First Broker Login flow, you see the authenticators used by default. You can re-configure the existing flow. For example, you can disable some authenticators, mark some of them as required, or configure some authenticators.\nYou can also create a new authentication flow, write your own Authenticator implementations, and use it in your flow. See Server Developer Guide for more information.\nDefault first login flow authenticators\nReview Profile\nThis authenticator displays the profile information page, so the users can review their profile that Keycloak retrieves from an identity provider.\nYou can set the Update Profile On First Login option in the Actions menu."},
  {"id": "_identity_broker_post_login_flow", "title": "Post login flow", "breadcrumb": ["Integrating identity providers"], "url": "index.html#_identity_broker_post_login_flow", "md": "md/_identity_broker_post_login_flow.md", "text": "Post login flow is useful for the situations when you want to trigger some additional authentication actions after every login with the particular identity provider. For example, you may want to trigger 2-factor authentication after every login of Keycloak to Facebook because Facebook does not provide 2-factor authentication during its login.\nOnce you setup the authentication flow with the needed steps, set it as Post login flow when configuring the identity provider.\nPost login flow examples\nRequesting 2-factor authentication after identity provider login\nThe easiest way is to enforce authentication with one particular 2-factor method. For example, when requesting OTP, the flow can look like this with only a single authenticator configured. This type of flow asks the user to configure the OTP during the first login with the identity provide when the user does not have OTP set on the account.\n2FA post login flow with OTP\nThe more complex setup can include multiple 2-factor authentication methods configured as ALTERNATIVE. In this case, make sure that the user is requested to setup one of the methods if that user does not yet have any 2-factor authentication configured on the account. This could be done as follows:\nMake sure that one of the 2-factor methods is configured as REQUIRED in the First login flow. This method can works if you expect all your users to be registered by the identity provider login.\nWrap the 2-factor methods as ALTERNATIVE into a conditional subflow such as one called 2FA and create another conditional subflow such as one called OTP if no 2FA, which will be triggered only if the previous subflow was not executed and will ask user to add one of the 2-factor methods (for example, OTP). The example of a similar flow configuration is provided in the Conditions section of the Authentication flows chapter.\nRequesting additional authentication steps for the dedicated clients\nIn some cases, a client or group of clients may need to perform some"},
  {"id": "retrieving-external-idp-tokens", "title": "Retrieving external IDP tokens", "breadcrumb": ["Integrating identity providers"], "url": "index.html#retrieving-external-idp-tokens", "md": "md/retrieving-external-idp-tokens.md", "text": "With Keycloak, you can store tokens and responses from the authentication process with the external IDP using the Store Token configuration option on the IDP’s settings page.\nApplication code can retrieve these tokens and responses to import extra user information or to request the external IDP securely. For example, an application can use the Google token to use other Google services and REST APIs.\nFor the details on how to configure and use this functionality, please see the section for retrieving external IDP tokens from Server Developer Guide."},
  {"id": "link-existing-user-to-the-identity-provider", "title": "Link existing user to the identity provider", "breadcrumb": ["Integrating identity providers"], "url": "index.html#link-existing-user-to-the-identity-provider", "md": "md/link-existing-user-to-the-identity-provider.md", "text": "In the typical usage, the identity provider will automatically register new user to the Keycloak storage once user is authenticated to the Keycloak with the identity provider for the first time. Details about this are described in the First login flow.\nHowever in many cases, it may be desired to link existing Keycloak user to the identity provider. This is useful, so that user can login with the identity provider during his next authentication to Keycloak. Another use is, that application may need to use existing tokens from identity provider. For example application may want to use Facebook API, so it will need user to link his Keycloak user account with his Facebook account to be then able to retrieve Facebook token from Keycloak and use it as described in the corresponding section from Server Developer Guide.\nThe easiest is to use Account console from where the user can directly link his account to the particular identity provider. It is also possible to directly trigger process of linking user with the identity provider from your own application. This is possible with the use of Client initiated account linking API. This API is used under the covers by the built-in Keycloak account console. For the details about this API, see the corresponding section from Server Developer Guide."},
  {"id": "identity-broker-logout", "title": "Identity broker logout", "breadcrumb": ["Integrating identity providers"], "url": "index.html#identity-broker-logout", "md": "md/identity-broker-logout.md", "text": "When logging out, Keycloak sends a request to the external identity provider that is used to log in initially and logs the user out of this identity provider."},
  {"id": "sso-protocols", "title": "SSO protocols", "breadcrumb": [], "url": "index.html#sso-protocols", "md": "md/sso-protocols.md", "text": "This section discusses authentication protocols, the Keycloak authentication server and how applications, secured by the Keycloak authentication server, interact with these protocols."},
  {"id": "con-oidc_server_administration_guide", "title": "OpenID Connect", "breadcrumb": ["SSO protocols"], "url": "index.html#con-oidc_server_administration_guide", "md": "md/con-oidc_server_administration_guide.md", "text": "OpenID Connect (OIDC) is an authentication protocol that is an extension of OAuth 2.0.\nOAuth 2.0 is a framework for building authorization protocols and is incomplete. OIDC, however, is a full authentication and authorization protocol that uses the Json Web Token (JWT) standards. The JWT standards define an identity token JSON format and methods to digitally sign and encrypt data in a compact and web-friendly way.\nIn general, OIDC implements two use cases. The first case is an application requesting that a Keycloak server authenticates a user. Upon successful login, the application receives an identity token and an access token. The identity token contains user information including user name, email, and profile information. The realm digitally signs the access token which contains access information (such as user role mappings) that applications use to determine the resources users can access in the application.\nThe second use case is a client accessing remote services.\nThe client requests an access token from Keycloak to invoke on remote services on behalf of the user.\nKeycloak authenticates the user and asks the user for consent to grant access to the requesting client.\nThe client receives the access token which is digitally signed by the realm.\nThe client makes REST requests on remote services using the access token.\nThe remote REST service extracts the access token.\nThe remote REST service verifies the tokens signature.\nThe remote REST service decides, based on access information within the token, to process or reject the request.\nOIDC auth flows\nOIDC has several methods, or flows, that clients or applications can use to authenticate users and receive identity and access tokens. The method depends on the type of application or client requesting access.\nAuthorization Code Flow\nThe Authorization Code Flow is a browser-based protocol and suits authenticating and authorizing browser-based applications. It uses browser redirects to obtain identity and access tokens."},
  {"id": "_saml", "title": "SAML", "breadcrumb": ["SSO protocols"], "url": "index.html#_saml", "md": "md/_saml.md", "text": "SAML 2.0 is a similar specification to OIDC but more mature. It is descended from SOAP and web service messaging specifications so is generally more verbose than OIDC. SAML 2.0 is an authentication protocol that exchanges XML documents between authentication servers and applications. XML signatures and encryption are used to verify requests and responses.\nIn general, SAML implements two use cases.\nThe first use case is an application that requests the Keycloak server authenticates a user. Upon successful login, the application will receive an XML document. This document contains an SAML assertion that specifies user attributes. The realm digitally signs the document which contains access information (such as user role mappings) that applications use to determine the resources users are allowed to access in the application.\nThe second use case is a client accessing remote services. The client requests a SAML assertion from Keycloak to invoke on remote services on behalf of the user.\nSAML bindings\nKeycloak supports three binding types.\nRedirect binding\nRedirect binding uses a series of browser redirect URIs to exchange information.\nA user connects to an application using a browser. The application detects the user is not authenticated.\nThe application generates an XML authentication request document and encodes it as a query parameter in a URI. The URI is used to redirect to the Keycloak server. Depending on your settings, the application can also digitally sign the XML document and include the signature as a query parameter in the redirect URI to Keycloak. This signature is used to validate the client that sends the request.\nThe browser redirects to Keycloak.\nThe server extracts the XML auth request document and verifies the digital signature, if required.\nThe user enters their authentication credentials.\nAfter authentication, the server generates an XML authentication response document. The document contains a SAML assertion that holds metadata about the user,"},
  {"id": "ref-saml-vs-oidc_server_administration_guide", "title": "OpenID Connect compared to SAML", "breadcrumb": ["SSO protocols"], "url": "index.html#ref-saml-vs-oidc_server_administration_guide", "md": "md/ref-saml-vs-oidc_server_administration_guide.md", "text": "The following lists a number of factors to consider when choosing a protocol.\nFor most purposes, Keycloak recommends using OIDC.\nOIDC\nOIDC is specifically designed to work with the web.\nOIDC is suited for HTML5/JavaScript applications because it is easier to implement on the client side than SAML.\nOIDC tokens are in the JSON format which makes them easier for Javascript to consume.\nOIDC has features to make security implementation easier. For example, see the iframe trick that the specification uses to determine a users login status.\nSAML\nSAML is designed as a layer to work on top of the web.\nSAML can be more verbose than OIDC.\nUsers pick SAML over OIDC because there is a perception that it is mature.\nUsers pick SAML over OIDC existing applications that are secured with it."},
  {"id": "_docker", "title": "Distribution Registry v2 authentication", "breadcrumb": ["SSO protocols"], "url": "index.html#_docker", "md": "md/_docker.md", "text": "Docker authentication is disabled by default. To enable docker authentication, see the Enabling and disabling features guide.\nDistribution Registry V2 Authentication is a protocol, similar to OIDC, that authenticates users against Distribution registries. Keycloak’s implementation of this protocol lets Docker clients use a Keycloak authentication server authenticate against a registry. This protocol uses standard token and signature mechanisms but it does deviate from a true OIDC implementation. It deviates by using a very specific JSON format for requests and responses as well as mapping repository names and permissions to the OAuth scope mechanism.\nDocker authentication flow\nThe authentication flow is described in the Docker API documentation. The following is a summary from the perspective of the Keycloak authentication server:\nPerform a docker login.\nThe Docker client requests a resource from the Distribution registry. If the resource is protected and no authentication token is in the request, the Distribution registry server responds with a 401 HTTP message with some information on the permissions that are required and the location of the authorization server.\nThe Docker client constructs an authentication request based on the 401 HTTP message from the Distribution registry. The client uses the locally cached credentials (from the docker login command) as part of the HTTP Basic Authentication request to the Keycloak authentication server.\nThe Keycloak authentication server attempts to authenticate the user and return a JSON body containing an OAuth-style Bearer token.\nThe Docker client receives a bearer token from the JSON response and uses it in the authorization header to request the protected resource.\nThe Distribution registry receives the new request for the protected resource with the token from the Keycloak server. The registry validates the token and grants access to the requested resource (if appropriate).\nKeycloak does not create a browser SSO"},
  {"id": "_admin_permissions", "title": "Managing access to realm resources", "breadcrumb": [], "url": "index.html#_admin_permissions", "md": "md/_admin_permissions.md", "text": "Each realm created on the Keycloak has a dedicated Admin Console from which that realm can be managed. The master realm is a special realm that allows admins to manage more than one realm on the system. You can also define fine-grained access to users in different realms to manage the server. This chapter goes over all the scenarios for this."},
  {"id": "_master_realm_access_control", "title": "Master realm access control", "breadcrumb": ["Managing access to realm resources"], "url": "index.html#_master_realm_access_control", "md": "md/_master_realm_access_control.md", "text": "The master realm in Keycloak is a special realm and treated differently than other realms. Users in the Keycloak master realm can be granted permission to manage zero or more realms that are deployed on the Keycloak server. When a realm is created, Keycloak automatically creates various roles that grant permissions to access that new realm. Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the master realm. It’s possible to create multiple superusers, as well as users that can only manage specific realms.\nGlobal roles\nThere are two realm-level roles in the master realm. These are:\nadmin\ncreate-realm\nUsers with the admin role are superusers and have full access to manage any realm on the server. Users with the create-realm role are allowed to create new realms. They will be granted full access to any new realm they create.\nAdmins with the create-realm role who do not have the admin role will also need the realm-specific query-realms role to be able to create and list realms in the Admin Console.\nRealm specific roles\nAdmin users within the master realm can be granted management privileges to one or more other realms in the system. Each realm in Keycloak is represented by a client in the master realm. The name of the client is <realm name>-realm. These clients each have client-level roles defined which define varying level of access to manage an individual realm.\nThe roles available are:\ncreate-client\nimpersonation\nmanage-authorization\nmanage-clients\nmanage-events\nmanage-identity-providers\nmanage-organizations\nmanage-realm\nmanage-users\nquery-clients\nquery-groups\nquery-organizations\nquery-realms\nquery-users\nview-authorization\nview-clients\nview-events\nview-identity-providers\nview-organizations\nview-realm\nview-users\nAssign the roles you want to your users and they will only be able to use that specific part of the administration console.\nAdmins with the manage-users role will only be able to assign admin roles to"},
  {"id": "_per_realm_admin_permissions", "title": "Dedicated realm admin consoles", "breadcrumb": ["Managing access to realm resources"], "url": "index.html#_per_realm_admin_permissions", "md": "md/_per_realm_admin_permissions.md", "text": "Each realm has a dedicated Admin Console that can be accessed by going to the url /admin/{realm-name}/console. Users within that realm can be granted realm management permissions by assigning specific user role mappings.\nEach realm has a built-in client called realm-management. You can view this client by going to the Clients left menu item of your realm. This client defines client-level roles that specify permissions that can be granted to manage the realm.\ncreate-client\nimpersonation\nmanage-authorization\nmanage-clients\nmanage-events\nmanage-identity-providers\nmanage-organizations\nmanage-realm\nmanage-users\nquery-clients\nquery-groups\nquery-organizations\nquery-realms\nquery-users\nrealm-admin\nview-authorization\nview-clients\nview-events\nview-identity-providers\nview-organizations\nview-realm\nview-users\nAssign the roles you want to your users and they will only be able to use that specific part of the administration console."},
  {"id": "_fine_grained_permissions", "title": "Delegating realm administration using permissions", "breadcrumb": ["Managing access to realm resources"], "url": "index.html#_fine_grained_permissions", "md": "md/_fine_grained_permissions.md", "text": "You can delegate realm management to other administrators, the realm administrators, using the fine-grained admin permissions feature. Different from the Role-Based Access Control (RBAC) Mechanism provided through the Global and Realm specific roles, this feature provides a more fine-grained control over how realm resources can be accessed and managed based on a well-defined set of operations that can be performed on them.\nBy relying on a Policy-Based Access Control, realm administrators can define permissions to realm resources such as users, groups, and clients, using different policy types, or access control methods, so that a realm administrator is limited to access a subset of realm resources and their operations.\nThe feature provides an alternative to the aforementioned RBAC mechanism, but it does not replace it. You are still able to grant administrative roles like view-users or manage-clients to delegate access to realm administrators but doing so will skip the mechanisms provided by this feature.\nEnforcing access to realm resources only applies when managing resources through the administration console or the Admin API.\nUnderstanding the different types of realm administrators\nThere are three different types of realm administrators when managing a realm:\nServer administrators: These are users (or service accounts) that have been granted with the admin role in the master realm.\nRealm administrators: These are users (or service accounts) that have been granted with the realm-admin role in a specific realm.\nDelegated realm administrators: These are users (or service accounts) other than the types above but granted access to manage a realm through the fine-grained admin permissions feature.\nBoth server and realm administrators can manage a realm with full access to all their resources and administrative operations. The main difference between them is that server administrators can manage any realm in the server, while realm administrators can only manage the"},
  {"id": "fine-grained-admin-permissions-v1", "title": "Fine grained admin permissions V1", "breadcrumb": ["Managing access to realm resources"], "url": "index.html#fine-grained-admin-permissions-v1", "md": "md/fine-grained-admin-permissions-v1.md", "text": "Preview feature fine-grained admin permissions V1 has been replaced by a new supported version. Version 1 of the feature is still available, but it has been deprecated and will be removed in future release. To enable it, start the server with --features=admin-fine-grained-authz:v1.\nSometimes roles like manage-realm or manage-users are too coarse grain and you want to create restricted admin accounts that have more fine grain permissions. Keycloak allows you to define and assign restricted access policies for managing a realm. Things like:\nManaging one specific client\nManaging users that belong to a specific group\nManaging membership of a group\nLimited user management.\nFine grain impersonation control\nBeing able to assign a specific restricted set of roles to users.\nBeing able to assign a specific restricted set of roles to a composite role.\nBeing able to assign a specific restricted set of roles to a client’s scope.\nNew general policies for viewing and managing users, groups, roles, and clients.\nThere are some important things to note about fine grain admin permissions:\nFine grain admin permissions were implemented on top of Authorization Services. It is highly recommended that you read up on those features before diving into fine grain permissions.\nFine grain permissions are only available within dedicated admin consoles and admins defined within those realms. You cannot define cross-realm fine grain permissions.\nFine grain permissions are used to grant additional permissions. You cannot override the default behavior of the built-in admin roles.\nManaging one specific client\nLet’s look first at allowing an admin to manage one client and one client only. In our example, we have a realm called test and a client called sales-application. In the realm test we will give a user in that realm permission to only manage that application.\nYou cannot do cross realm fine grain permissions. Admins in the master realm are limited to the predefined admin roles defined in"},
  {"id": "_managing_organizations", "title": "Managing organizations", "breadcrumb": [], "url": "index.html#_managing_organizations", "md": "md/_managing_organizations.md", "text": "When integrating with a third party like a customer or business partner, you might want to manage their identities separately from others and build a unified and secure experience throughout your business ecosystem when they interact with a realm.\nIn a realm, an organization represents these third parties so that a realm or an organization administrator can manage the entire lifecycle of its members and how they authenticate and authorize to a realm, on a per-organization basis.\nThe organization is the entry point to start using the IAM capabilities of Keycloak to also address Business-to-Business (B2B) use cases. It enables multi-tenancy within a realm so that users can have access to protected resources from a realm but with a more restricted and controlled context, that context being the organization to which they belong.\nKeycloak Organizations is a feature that enables support for organizations in Keycloak. For now, it provides some of the core capabilities needed to manage organizations such as:\nManage members\nOrganize members into groups with hierarchical structures\nOnboard organization members using invitation links\nOnboard organization members by federating their identities through identity brokering\nShare identity providers across multiple organizations with independent per-association configuration\nIdentity-first login and organization-specific steps when authenticating in the scope of an organization\nPropagate organization-specific claims to applications through tokens for authorization purposes"},
  {"id": "_enabling_organization_", "title": "Enabling organizations in Keycloak", "breadcrumb": ["Managing organizations"], "url": "index.html#_enabling_organization_", "md": "md/_enabling_organization_.md", "text": "To use organizations, you have to enable the feature for the current realm.\nProcedure\nClick Realm Settings in the menu.\nToggle Organizations to On.\nClick Save\nEnabling Organizations\nOnce the feature is enabled, you are able to manage organizations through the Organizations section available from the menu."},
  {"id": "managing-an-organization", "title": "Managing an organization", "breadcrumb": ["Managing organizations"], "url": "index.html#managing-an-organization", "md": "md/managing-an-organization.md", "text": "From the Organizations section, you can manage all the organizations in your realm.\nManaging organizations\nCreating an organization\nProcedure\nClick Create Organization.\nCreating organization\nAn organization has the following settings:\nName\nA user-friendly name for the organization. The name is unique within a realm.\nAlias\nAn alias for this organization, used to reference the organization internally. The alias is unique within a realm. ASCII spaces, control characters, and backslashes are not allowed. The alias * is reserved for requesting all organizations, but * can occur within an alias such as acme*corp. Characters such as / and : are allowed. Unicode characters and double quotes remain accepted for backward compatibility, although they are outside the OAuth 2.0 scope-token character range. Encode aliases appropriately when including them in URLs. If not set, Keycloak will attempt to use the name as the alias. If the name contains forbidden characters, you will get an error and will be asked to specify an alias. Once defined, the alias cannot be changed afterwards.\nRedirect URL (deprecated)\nThis field is deprecated and will be removed in a future release. When sending invitations, prefer specifying a client_id to control where users are redirected. The redirect URL is only used when invitations are sent without a custom client; in that case, the URL must be listed as a valid redirect URI in the account client. If the URL does not match the client’s allowed redirect URIs, or if this field is left empty, the user is redirected to the account console instead. When a custom client is specified in the invitation, this field is ignored.\nDomains\nA set of zero or more domains that belongs to this organization. A domain cannot be shared by different organizations within a realm. When no domain is specified, organization members will not be validated against domain restrictions during authentication and profile validation.\nDescription\nA free-text field to describe the"},
  {"id": "managing-organization-domains_server_administration_guide", "title": "Managing organization domains", "breadcrumb": ["Managing organizations"], "url": "index.html#managing-organization-domains_server_administration_guide", "md": "md/managing-organization-domains_server_administration_guide.md", "text": "The domain associated with an organization plays an important role in how organization members authenticate to a realm and how their profiles are validated.\nOne of the key roles of a domain is to help to identify the organizations where a user is a member. By looking at their email address, Keycloak will match a corresponding organization using the same domain and eventually change the authentication flow based on the organization requirements.\nDomains are first-class entities with their own configuration. In addition to identifying the organization, each domain can be configured with identity provider routing and auto-redirect settings that control how users matching that domain are authenticated.\nThe domain also allows organizations to enforce that users are not allowed to use a domain in their emails other than those associated with an organization. This restriction is especially useful when users, and their identities, are federated from identity providers associated with an organization and you want to force a specific email domain for their email addresses.\nAssigning domains\nDomains are assigned through the Domains tab when managing an organization. An organization can have zero, one, or multiple domains.\nWhen no domain is assigned, members are not validated against domain restrictions and email-based redirection to identity providers is unavailable. A domain-less organization can still use auto-membership through a linked identity provider — see Authenticating members for details.\nDomain types\nExact\nMatches only the specified value. example.com matches user@example.com but not user@sub.example.com.\nWildcard\nPrefix the base domain with *. to match the base domain and all its subdomains at any depth. *.example.com matches user@example.com, user@sub.example.com, and user@deep.sub.example.com.\nMapping email addresses to organizations\nKeycloak extracts the domain from the email address, normalizes it to lowercase, and selects the best-matching organization"},
  {"id": "_managing_attributes_", "title": "Managing attributes", "breadcrumb": ["Managing organizations"], "url": "index.html#_managing_attributes_", "md": "md/_managing_attributes_.md", "text": "An administrator can store additional metadata about an organization using attributes. An organization attribute is a key/value pair that can hold multiple string values.\nFor that, click the Attributes tab and set any attribute you want by providing a key and a value.\nTo provide multiple values for the same attribute, and key, just add another attribute with the same key but with a different value.\nManaging organization attributes"},
  {"id": "_managing_members_", "title": "Managing members", "breadcrumb": ["Managing organizations"], "url": "index.html#_managing_members_", "md": "md/_managing_members_.md", "text": "An organization member is basically a realm user but with a link to one or more organizations. They are logically separated from other users in a realm so that you know exactly which users belong to an organization.\nThere are different ways to add, or onboard, a member to an organization:\nAdding an existing realm user as a member\nThrough an identity provider associated with an organization\nSending an invitation to create a new account\nSending an invitation to an existing user to join an organization\nOnce a member of an organization, that user’s account can be managed just like any regular account in a realm by accessing the Users section in the menu.\nHowever, you can narrow the users to only those associated with an organization by accessing the Members tab when managing an organization. In this tab, you have a list of all the organization members and actions to add new members and to edit and remove existing ones.\nManaging organization members\nYou are also able to manage the membership of a user in an organization from the Users section. When you select a user, you can see the list of organizations that the user belongs to and manage those memberships.\nManaging organization members\nManaged and unmanaged members\nWhen managing members, consider how their relationship with an organization affects the lifecycle of their accounts. Members can join an organization through different flows and each flow indicates the strength of the link between their accounts and the organization.\nThere are two types of members:\nManaged\nUnmanaged\nManaged members are those managed by the organization, and they cannot exist outside of their organization. For instance, consider an account created through an identity provider whose link to the organization is configured with the Managed membership type. That account does not belong to a realm as it was federated from the organization. In this case, the single source of truth for the identity is the organization and its lifecycle is"},
  {"id": "_managing_groups_", "title": "Managing groups", "breadcrumb": ["Managing organizations"], "url": "index.html#_managing_groups_", "md": "md/_managing_groups_.md", "text": "Organization groups let you organize members into logical teams, departments, or any hierarchical structure that makes sense for your organization. Think of them as folders for your users—simple, flexible, and powerful.\nUnlike realm groups that are shared across your entire realm, organization groups belong exclusively to one organization. This means orgA and orgB can each have a /Engineering/Backend group without any conflict—each is a completely separate group with its own unique identifier.\nCreating groups\nNavigate to your organization and click the Groups tab.\nManaging organization groups\nProcedure\nClick Create group.\nProvide a Name for the group.\nClick Create.\nOptionally, before creating the group, navigate to Parent group to create nested structures.\nYour group is ready. You can now add members, nest more groups under it, or set attributes.\nBuilding hierarchies\nGroups can be nested to create organizational structures that mirror your real-world teams:\n/Engineering\n  /Engineering/Backend\n  /Engineering/Frontend\n/Sales\n  /Sales/APAC\n  /Sales/EMEA\n  /Sales/LATAM\n  /Sales/NA\nCreate a child group by selecting its parent before creation, or move groups, by clicking Move to in the UI to reorganize them.\nAdding members to groups\nMembers join groups the same way they join realm groups.\nProcedure\nSelect the group.\nClick the Members tab.\nClick Add member.\nSelect one or more organization members.\nClick Add.\nTo automatically assign members to these groups when they authenticate via an Identity Provider, see Mapping federated users to organization groups.\nTo view which organization groups a specific member belongs to, use the kebab menu (⋮) next to the member and select Show group memberships. For details, see Viewing organization group memberships.\nUnderstanding group paths\nEvery group has a path that describes its location in the hierarchy. Paths are relative to the organization, not the realm.\nFor example:\nOrganization A has /Engineering/Backend\nOrganization B has"},
  {"id": "_managing_identity_provider_", "title": "Managing identity providers", "breadcrumb": ["Managing organizations"], "url": "index.html#_managing_identity_provider_", "md": "md/_managing_identity_provider_.md", "text": "An organization might have its own identity provider as the single source of truth for their identities. In this case, you want to configure the organization to authenticate users using the organization’s identity provider, federate their identities, and finally add them as a member of the organization.\nAn organization can have one or more identity providers associated with it so that they can authenticate their users from different sources and enforce different constraints on each of them.\nA single identity provider can also be shared across multiple organizations. Each organization maintains its own independent link to the identity provider, with per-association settings that control auto-membership and membership type. This enables scenarios where a single corporate identity provider serves multiple business units, each with its own membership rules.\nBefore you can link an identity provider to an organization, you create an identity provider at the realm level from the Identity Providers section in the menu. You can link any of the built-in social and identity providers available in the realm to an organization.\nLinking an identity provider to an organization\nAn identity provider can be linked to an organization from the Identity providers tab. If identity providers are already linked, you see a list of them with their per-association settings and options to edit or unlink.\nOrganization identity providers\nProcedure\nClick Link identity provider\nSelect an Identity provider\nConfigure the per-association settings\nClick Save\nLinking identity provider\nWhen linking an identity provider to an organization, the following per-association settings are available:\nIdentity provider\nThe identity provider you want to link to the organization. A single identity provider can be linked to multiple organizations.\nAuto membership\nWhen enabled, users who authenticate through this identity provider are automatically added as members of the organization, subject to the domain gate"},
  {"id": "authenticating-members_server_administration_guide", "title": "Authenticating members", "breadcrumb": ["Managing organizations"], "url": "index.html#authenticating-members_server_administration_guide", "md": "md/authenticating-members_server_administration_guide.md", "text": "When you enable organizations for a realm, user authentication is changed. If the user is recognized to be authenticating in the context of an organization, the authentication flow changes on a per-organization basis.\nWhen a realm is created, the authentication flows are automatically updated to enable specific steps to authenticate and onboard organization members. The authentication flows updated are:\nbrowser\nfirst broker login\nThe main change to the browser flow is that it defaults to an identity-first login so that users are identified before prompting for their credentials. Concerning the first broker login flow, the main change is the ability to automatically add users as organization members once they authenticate through an identity provider associated with an organization and successfully complete the flow. Whether a user is actually added depends on the per-association configuration of the identity provider link — specifically the auto-membership and membership type settings (see Managing identity providers) — and the domain gate, which checks that the user’s email domain is claimed by the organization.\nThe choice to use an identity-first login or not depends on the existence of an organization in a realm. If no organizations exist, the user follows the usual steps to authenticate using the username and password, or any other step configured in the browser flow. Otherwise, the user is asked first for a username or email to continue authenticating to a realm.\nThe identity-first login main goal is to identify the user:\nIs the user an existing or a new user?\nIs the user a member of any organization within a realm?\nIf an organization member, is the user linked to any identity provider associated with the organization?\nDepending on the outcome when identifying the user, the authentication flow changes to either proceed with authentication by asking for the user’s credentials or eventually redirect the user automatically to authenticate within"},
  {"id": "common-organization-setup-recipes_server_administration_guide", "title": "Common setup recipes", "breadcrumb": ["Managing organizations"], "url": "index.html#common-organization-setup-recipes_server_administration_guide", "md": "md/common-organization-setup-recipes_server_administration_guide.md", "text": "This section provides step-by-step instructions for common organization configurations. Each recipe shows how to achieve a specific outcome using identity provider links, domain routing, and auto-membership settings.\nFor the full details on the settings referenced in these recipes, see Managing identity providers, Managing organization domains, and Authenticating members.\nSingle identity provider with automatic managed membership\nGoal: Users from a known email domain authenticate through the organization’s identity provider and are automatically added as managed members.\nPrerequisites: An identity provider created at the realm level.\nProcedure\nCreate an organization with a domain (for example, acme.com).\nGo to the organization’s Identity providers tab and click Link identity provider.\nSelect the identity provider, set Auto membership to ON and Membership type to Managed. Click Save.\nGo to the organization’s Domains tab and click the domain (acme.com).\nSelect the linked identity provider from the dropdown and enable Auto redirect. Click Save.\nResult: When a user enters an email like alice@acme.com on the login page, they are automatically redirected to the identity provider. After authenticating, they are added to the organization as a managed member. If the organization or the membership is removed, the user’s account is also removed from the realm.\nMultiple domains with different identity providers\nGoal: A single organization authenticates users from different email domains through different identity providers, with different membership types.\nPrerequisites: Two identity providers created at the realm level (for example, idp-corporate and idp-partner).\nProcedure\nCreate an organization with two domains (for example, acme.com and partner.com).\nGo to the organization’s Identity providers tab:\nLink idp-corporate with Auto membership ON and Membership type set to Managed.\nLink idp-partner with Auto membership ON and Membership type set to Unmanaged.\nGo to the"},
  {"id": "_mapping_organization_claims_", "title": "Mapping organization claims", "breadcrumb": ["Managing organizations"], "url": "index.html#_mapping_organization_claims_", "md": "md/_mapping_organization_claims_.md", "text": "To map organization-specific claims into tokens, a client needs to request the organization scope when sending authorization requests to the server. When authenticating in the context of an organization, clients can request the organization scope to map information about the organizations where the user is a member.\nAs a result, the token will contain a claim as follows:\n\"organization\": {\n  \"testcorp\": {\n    \"id\": \"42c3e46f-2477-44d7-a85b-d3b43f6b31fa\",\n    \"attr1\": [\n      \"value1\"\n    ]\n  }\n}\nThe organization claim can be used by clients (for example, from ID Tokens) and resource servers (for example, from access tokens) to authorize access to protected resources based on the organization where the user is a member.\nThe organization scope is a built-in optional client scope at the realm. Therefore, this scope is added to any client created in the realm by default. It also defines the Organization Membership mapper that controls how the organization membership information is mapped to the tokens.\nBy default, the organization id and attributes are not included in the organization claim. To include them, edit the mapper and enable the Add organization id and Add organization attributes options, respectively.\nIncluding attributes in the organization claim\nThe organization scope is requested using different formats:\nFormat Description\norganization\nMaps to a single organization if the user is a member of a single organization. Otherwise, if a member of multiple organizations, the user will be prompted to select an organization when authenticating to the realm.\norganization:<alias>\nMaps to a specific organization with the given alias. Multiple organizations can be requested by specifying multiple scopes, for example organization:org-a organization:org-b. If any of the aliases does not match an existing organization or the user is not a member, the request will be rejected.\norganization:*\nMaps to all organizations the user is a member of.\nMixing different scope formats"},
  {"id": "_managing_workflows", "title": "Managing workflows", "breadcrumb": [], "url": "index.html#_managing_workflows", "md": "md/_managing_workflows.md", "text": "Keycloak Workflows is a powerful engine to automate and orchestrate realm administrative tasks, bringing key capabilities of Identity Governance and Administration (IGA) to your identity and access management infrastructure. By using workflows, you can implement policies and processes that govern the lifecycle of realm resources, such as users and clients, helping you to improve security, meet compliance requirements, and reduce administrative costs.\nAs a core component of IGA, identity lifecycle management is fully supported by workflows so that you can easily automate onboarding and offboarding processes, and other recurring administrative tasks. For example, you can define workflows to:\nProvision and de-provision realm resources, such as users, automatically based on specific events or conditions.\nAutomate Joiner-Mover-Leaver (JML) processes to ensure that users are granted the appropriate access rights based on their roles and responsibilities.\nEnforce access reviews and certifications to ensure that users have the appropriate access rights.\nEnforce Just-In-Time and Least Privilege access by automating role assignments and revocations.\nEnforce strong authentication policies for realm users.\nPrevent insider data breaches by automating the removal of inactive or obsolete users.\nBy leveraging workflows, realm administrators can ensure that security policies are consistently enforced and based on the least privilege principle, reduce the risk of human error, and free up valuable time to focus on other important administrative tasks. This guide will walk you through the process of creating and managing workflows to automate your administrative tasks and implement IGA best practices when managing realms."},
  {"id": "_understanding_workflows_", "title": "Understanding workflows", "breadcrumb": ["Managing workflows"], "url": "index.html#_understanding_workflows_", "md": "md/_understanding_workflows_.md", "text": "A workflow is an activity or process within Keycloak that executes a series of predefined steps on a specific realm resource in response to specific events and based on the defined conditions.\nIn Keycloak, there are two main types of events:\nUser Events: These events are initiated by users, such as login in or registering a new account.\nAdmin Events: These events are initiated by administrators through the Admin Console and API, such as creating or updating a user or any other realm resource.\nWorkflows are designed to respond to these events by automating tasks and processes that need to be performed and executed on the realm resources associated with these events.\nOnce an event is fired, the workflow engine evaluates all defined workflows in the realm to determine if any should be triggered based on the event type and the specified conditions. If the event matches the conditions defined in a workflow, a workflow execution is created and assigned with an identifier. The workflow execution is bound to the realm resource associated with the event, and only a single instance of a workflow can be active for that realm resource at any given time.\nA realm resource can be any entity within the realm, such as a user, client, group, or a role. At the moment, workflows can be defined for the following realm resources:\nUsers\nOnce a workflow is active for a realm resource, its step chain is processed. The steps run sequentially, and they will run immediately or be scheduled to execute later in time, depending on each step configuration. Once all the steps are executed, the workflow execution is completed and the realm resource is no longer bound to that workflow.\nThat is the main gist of Keycloak Workflows. There are more details and settings that can be configured to customize the behavior and the lifecycle of a workflow, how their instances are created, managed, and bound to realm resources, as well as how their steps are executed."},
  {"id": "_understanding_workflow_definition_", "title": "Understanding the workflow definition", "breadcrumb": ["Managing workflows"], "url": "index.html#_understanding_workflow_definition_", "md": "md/_understanding_workflow_definition_.md", "text": "Workflows are defined in YAML format. This format allows for a clear and human-readable way to specify the automation process represented by a workflow.\nIn its simplest form, a workflow definition can be defined as follows:\nname: Onboarding new users\non: user-created\nsteps:\n  - uses: notify-user\n    with:\n      message: |\n        <p>Dear ${user.firstName} ${user.lastName}, </p>\n\n        <p>Welcome to ${realm.displayName}!</p>\n\n        <p>\n           Best regards,<br/>\n           ${realm.displayName} Team\n        </p>\n  - uses: add-required-action\n    after: 30d\n    with:\n      action: UPDATE_PASSWORD\n  - uses: restart\n    with:\n      position: 1\nThe example above is very simple but illustrates the core structure and the flexibility of a workflow to automate administrative tasks. It is composed of three main sections:\nname: A unique and user-friendly name to identify the workflow within the realm.\non: The event that will trigger the workflow. In this case, the workflow is triggered when a new user is added to the realm.\nsteps: A set of one or more steps to be executed when executing a workflow execution. In this example, three steps are defined:\nThe first step uses the built-in notify-user action to send a welcome message to the new user.\nThe second step uses the built-in add-required-action action to require the user to update their password after 30 days.\nThe third step uses the built-in restart action to restart the workflow from the second step so that the user is forced to update their password every 30 days.\nHere is a more detailed look at all settings available from the workflow definition:\nname\nA unique and user-friendly name to identify the workflow within the realm. This name is crucial for management and logging purposes. This setting is mandatory.\non\nDefine a condition that determines the event that will trigger the workflow. The condition is written using an expression language that supports a variety of checks on the event. See Triggering workflows on"},
  {"id": "_workflow_expression_language_", "title": "Understanding the workflow expression language", "breadcrumb": ["Managing workflows"], "url": "index.html#_workflow_expression_language_", "md": "md/_workflow_expression_language_.md", "text": "Some settings from the workflow definition can be defined using a boolean expression language, the Workflow Expression Language. Expressions are defined using functions, operands, and logical operators. The functions available in an expression will depend on the setting where it is being defined.\nThe functions can have zero or more arguments, and they can be combined with the following logical operators and symbols to define complex expressions:\nOperator Description\nand\nLogical AND\nor\nLogical OR\nnot\nLogical NOT\n()\nGrouping and delimiting conditional logic\nThese examples are all valid expressions:\nf1\nf1 and f2\nnot (f1 and f2)\n(f1 and f2) or f3\nThe settings that supports expressions provide its own set of functions as you will see in the following sections."},
  {"id": "_managing_workflows_", "title": "Managing workflows", "breadcrumb": ["Managing workflows"], "url": "index.html#_managing_workflows_", "md": "md/_managing_workflows_.md", "text": "Workflows can be managed through the Admin Console or the Admin REST API.\nOnly realm administrators with the appropriate permissions can manage workflows as they are considered sensitive operations. For more details, see Understanding different types of Realm Admins.\nManaging workflows through the Admin Console\nTo manage workflows through the Admin Console, you can follow these steps:\nProcedure\nClick Workflows in the menu.\nEmpty workflows list\nIf your realm does not have any workflows defined yet, you will see an empty list. To create a new workflow, click Create.\nCreating a new workflow\nThis will open the workflow creation screen where you can define the workflow using YAML format. To save the workflow, click Save.\nOnce you have created one or more workflows, they will be listed in the workflows list.\nList of workflows\nFrom the workflows list, you can perform the following actions:\nCreate: Click Create workflow to create a new workflow.\nUpdate: Click on the name of an existing workflow to update it.\nEnable/Disable: Use the toggle button on the Status column to enable or disable a workflow.\nCopy: Click on the Copy button next to a workflow to create a copy of it. This is useful if you want to create a new workflow based on an existing one.\nDelete: Click on the Delete button next to a workflow to delete it.\nUpdating a workflow\nTo update a workflow, click on its name in the workflows list. This will open the workflow in edit mode, where you can modify its YAML definition. After making your changes, click Save to apply the updates.\nThere are limitations when updating workflows if they have scheduled steps. In such cases, you are not able to change the step chain of a workflow if there are active instances of the workflow being updated. This limitation is in place to ensure the integrity of ongoing workflow instances where updates to the step chain could lead to an expensive operation of migrating existing instances to the new step chain, which could impact system"},
  {"id": "_workflow_events_", "title": "Triggering workflows on events", "breadcrumb": ["Managing workflows"], "url": "index.html#_workflow_events_", "md": "md/_workflow_events_.md", "text": "The on setting defines the event that will trigger the workflow. You should choose the event accordingly to the realm resource and the intent of the workflow.\nThe value of the `on' setting is an expression that must evaluate to true. In its basic form, the expression is simply the name of the event.\non: user-created\nAs you can see, events are functions in an expression and, as such, they also support parameters to provide more specific conditions. For example, to trigger a workflow when a user is added to a specific group, you can use the following expression:\non: user-group-membership-added(/mygroup)\nYou can also combine multiple conditions using logical operators. For example, to trigger a workflow when a user is created or when they authenticate, you can use:\non: user-created or user-authenticated\nEven though the on setting can be defined using expressions, keep in mind that a single event triggers a workflow.\nIf this setting is not specified, the workflow will not be triggered by any event, but workflow executions can still be created manually for a specific realm resource.\nAt the moment, workflows support event functions for the following realm resources:\nEvent functions\nEvent Description Parameters\nuser-created\nUser is added to the realm.\nNone\nuser-authenticated\nUser authenticates to the realm.\nThe client id of the client acting on behalf of the user when authenticating.\nuser-federated-identity-added\nUser is federated or when the account is linked to an identity provider.\nThe identity provider alias.\nuser-federated-identity-removed\nUser’s federated identity is removed or unlinked from an identity provider.\nThe identity provider alias.\nuser-role-granted\nA role is granted to the user.\nThe role name.\nuser-role-revoked\nA role is revoked from the user.\nThe role name.\nuser-group-membership-added\nUser joined a group.\nThe group name or path\nuser-group-membership-removed\nUser is removed from a group.\nThe group name or path\nclient-created\nClient is added to the realm."},
  {"id": "_scheduling_workflows_", "title": "Scheduling workflows", "breadcrumb": ["Managing workflows"], "url": "index.html#_scheduling_workflows_", "md": "md/_scheduling_workflows_.md", "text": "Workflows can be scheduled to run periodically according to a defined interval. This is done using the schedule setting in the workflow definition.\nA key difference between event-based triggering and scheduled workflows is that scheduled workflows follows a passive execution model where the workflow engine periodically checks for realm resources that meet the defined condition.\nname: Track inactive users\nschedule:\n  after: 5s\n  batch-size: 100\nThis method of scheduling is useful for automating tasks that need to be performed regularly, such as cleaning up inactive users or enforcing specific policies on realm resources. It is an alternative to event-based triggering, but it can also be used in combination with it. When used together, the workflow will be triggered either by the defined event or by the schedule.\nWhen a workflow is scheduled, it will be triggered automatically at the defined interval. At each run, the workflow engine will query for the realm resources that matches the workflow’s condition and will create a workflow execution for each of them, up to the defined batch size. If no condition is defined, the workflow will be executed for all realm resources of the type associated with the workflow. In the example above, the workflow is scheduled to run every 5 seconds and will process up to 100 realm resources at each run.\nThe schedule setting supports the following parameters:\nafter: Defines the interval between each run of the workflow. It must be at least 1 second.\nbatch-size: Defines the maximum number of realm resources to process at each run. It must be greater than 0."},
  {"id": "_workflow_conditions_", "title": "Defining conditions", "breadcrumb": ["Managing workflows"], "url": "index.html#_workflow_conditions_", "md": "md/_workflow_conditions_.md", "text": "The optional if setting allows you to define the conditions, as expressions, that the target resource must meet in order for the workflow to be triggered. See Understanding the workflow expression language for more details.\nConditions provide fine-grained control over whether a workflow execution should be created. They allow you to inspect the context of the event and the state of the resource. For example, you can create conditions to check: * If a user has a specific attribute. * If a specific role is granted to a user or if the user is joining a specific group.\nIf the condition evaluates to true, the workflow execution is created. If it evaluates to false, no workflow execution is created, even though the expression from the on setting evaluates to true.\nJust like the on setting, the condition is written using an expression that supports a variety of checks on the realm resource associated with the event. For instance, considering a user_created event, you can define a condition to trigger the workflow only if the user has a specific attribute:\non: user-created\nif: has-user-attribute(plan=gold)\nIn this example, the workflow will only be triggered when a new user is created and that user has an attribute plan with the value gold.\nKeycloak provides a set of built-in conditions that you can use in your workflows. The conditions are also based on the realm resource associated with the event.\nUser functions\nCondition Description Parameters\nhas-user-attribute\nIf the user has an attribute set.\nThe attribute name and optionally the attribute value using a properties format. If multiple values, they should be separated by comma. If the value is omitted, only the presence of the attribute is checked.\nhas-role\nIf the user is granted with a specific role\nThe name of the role.\nhas-identity-provider-link\nIf the user is linked to an identity provider.\nThe alias of the identity provider.\nis-member-of\nIf the user is member of a specific group.\nThe name or path of the group."},
  {"id": "_workflow_steps_", "title": "Defining steps", "breadcrumb": ["Managing workflows"], "url": "index.html#_workflow_steps_", "md": "md/_workflow_steps_.md", "text": "The steps setting allows you to define the step chain, which is a sequence of actions to be executed during the lifetime of a workflow execution. Each step represents a specific action that can be performed, such as sending a notification, updating user attributes, or interacting with external systems.\nEach step in the step chain is defined using the following structure:\nsteps:\n  - uses: <step>\n    with:\n      <param>: <value>\n      ...\n    after: <duration>\n  ...\nIn its simplest form, a step is defined using only the uses field:\nsteps:\n  - uses: disable-user\nHowever, some steps also support additional settings to customize their behavior:\nsteps:\n  - uses: notify-user\n    with:\n      message: \"Welcome to the platform!\"\nHere is a more detailed look at all fields available from defining a step:\nuses\nThe name of the step to be executed. This field is mandatory.\nwith\nKey/value pairs to be passed to the step. The available parameters depend on the step being used. This field is optional.\nafter\nAn optional duration to wait before executing the step. The duration is defined using a number followed by a time unit:\nms: milliseconds\ns: seconds (default if no unit is specified)\nm: minutes\nh: hours\nd: days\nIn addition, ISO-8601 duration format is also supported, for example: P1DT2H (1 day and 2 hours). If no time unit is specified, it assumes seconds by default.\nKeycloak provides a set of built-in steps that you can use in your workflows. The steps are targeted at performing actions on the realm resource associated with the event, so that each realm resource type has its own set of steps.\nUser steps\nStep Description Configuration\nadd-required-action\nAdd a required action to the user\naction: The name of the required action\nremove-required-action\nRemove a required action from the user\naction: The name of the required action\ngrant-role\nGrant one or more roles to the user\nrole: One or more role names to grant. This can be a single value or a list of values (e.g., [value1, value2])"},
  {"id": "_understanding_workflows_engine_", "title": "Understanding the workflows engine", "breadcrumb": ["Managing workflows"], "url": "index.html#_understanding_workflows_engine_", "md": "md/_understanding_workflows_engine_.md", "text": "The lifecycle and execution of workflows in Keycloak is managed by the Workflows Engine. The engine is responsible for processing events, creating workflow executions, and processing their steps. Once a workflow execution is created, the engine takes over and manages the execution of its steps chain.\nThe execution of the steps chain is done asynchronously and detached from the request that originated the event that triggered the workflow. This means that workflows are not scheduled nor executed immediately within the context of the request, but rather sent to a task thread pool and scheduled to be executed later by the engine. This allows for better performance and scalability, as the steps can be executed in the background without blocking the main request thread.\nFor immediate steps, the engine processes them as soon as the workflow execution is submitted to the task thread pool. This means that immediate steps are executed right away, as soon as the workflow execution is picked up by a worker thread from the pool.\nFor scheduled steps, the engine continuously monitors the state of all active workflow executions in the realm. This is done by a background task that runs periodically to check for any workflow executions that have steps ready to be executed. The schedule steps of a workflow are also executed asynchronously by the background task, using the same task thread pool as immediate steps.\nConfiguring the scheduled steps execution interval\nBy default, the background task tracking due steps runs every 12 hours, but this interval can be configured by setting the following server configuration option:\nspi-events-listener—​workflow-event-listener—​step-runner-task-interval: Defines the interval at which the background task runs to check for workflow steps that are due for execution. It follows the same format used in the workflow step after field, where you can specify the interval as a number followed by a time unit (ms, s - default, m, h, d) or using the"},
  {"id": "_handling_failures_", "title": "Handling failures", "breadcrumb": ["Managing workflows"], "url": "index.html#_handling_failures_", "md": "md/_handling_failures_.md", "text": "The workflows engine keeps track of the execution process by storing the step that should run in a state table. If the step fails to run, either due to an error in the step execution or because of a timeout, the error is logged, an event is fired, and the state table remains unchanged. This effectively means that the step will be retried the next time the workflow execution task runs.\nIn this initial version there’s no limit to the number of retries, so a workflow execution can get stuck until the administrator intervenes and either fixes the issue that is preventing the step from running successfully or uses the API to cancel the workflow execution or to migrate the resource to a different workflow/step. Thus, it is important that admins monitor the workflow execution logs and check for any errors that may occur repeatedly.\nThe state table is used even for immediate steps (i.e. steps that are supposed to run immediately after the previous step). This means that if an immediate step fails, the workflow execution will be retried later, and the failed step will be retried as well, behaving as if it were a scheduled step. This is to ensure that the workflow execution process is consistent and that all steps are retried in the same way, regardless of their configuration. This also ensures the workflow will be resumed in case of server restarts or crashes.\nFuture versions of the workflows engine will include more features to handle failures, such as the ability to configure a maximum number of retries for each step, as well as the ability to define custom error handling logic for specific steps, like skip the step or cancel the workflow execution."},
  {"id": "_workflow_provider_events_", "title": "Listening to workflow provider events", "breadcrumb": ["Managing workflows"], "url": "index.html#_workflow_provider_events_", "md": "md/_workflow_provider_events_.md", "text": "During the lifecycle of a workflow execution, Keycloak fires a series of provider events that represent key moments such as activation, step execution, failures, and completion. SPI developers can listen to these events by implementing the ProviderEventListener interface and registering the listener with the KeycloakSessionFactory.\nKeycloak does not persist workflow execution history. By default, only log messages record what happened during a workflow run (see Troubleshooting workflows). Provider events allow you to capture and store workflow lifecycle data externally — for example, in an audit database or monitoring system — providing a complete execution trail beyond what the standard log messages offer.\nCommon event fields\nAll workflow provider events extend the WorkflowProviderEvent interface, which provides the following common fields:\nMethod Description\ngetKeycloakSession()\nThe KeycloakSession associated with this event.\ngetRealm()\nThe realm where the workflow event occurred.\ngetWorkflowId()\nThe ID of the workflow.\ngetWorkflowName()\nThe name of the workflow.\ngetResourceId()\nThe ID of the resource (user or client) associated with the workflow.\ngetResourceType()\nThe type of the resource — either USERS or CLIENTS.\ngetExecutionId()\nThe unique ID for this workflow execution.\nEvent types\nThe following event types are available:\nEvent Type Description Additional Fields\nWorkflowActivatedEvent\nFired when a workflow is activated for a resource — either through a trigger event, a schedule, or a manual API call.\ngetTriggerEventType(): The event provider ID that triggered activation (e.g., user-created, scheduled, or AD_HOC for manual activation).\nWorkflowDeactivatedEvent\nFired when a workflow execution is deactivated for a resource — for example, through a manual API call, a cancel-in-progress trigger, or because the resource no longer meets the workflow conditions.\ngetReason(): The reason for deactivation.\nWorkflowRestartedEvent\nFired when a workflow execution"},
  {"id": "_troubleshooting_workflows_", "title": "Troubleshooting workflows", "breadcrumb": ["Managing workflows"], "url": "index.html#_troubleshooting_workflows_", "md": "md/_troubleshooting_workflows_.md", "text": "When workflows are not behaving as expected, server logs are the primary tool for understanding what is happening. The workflow engine logs detailed information about workflow lifecycle events, step execution, and errors.\nEnabling workflow debug logging\nBy default, the workflow engine logs warnings and errors. To see the full execution flow, enable DEBUG level logging for the org.keycloak.models.workflow category by setting the following server configuration option:\n--log-level=org.keycloak.models.workflow:debug\nThis enables debug logging for the workflow engine, all step providers, and the workflow state provider.\nWhat to look for in the logs\nWorkflow activation and scheduling\nWhen a workflow is triggered by an event, the engine logs the activation and scheduling of the first step:\nWorkflow '<name>' activated for resource <id> (execution id: <id>) — the workflow execution has been created and is being processed.\nScheduled step <step> to run in <duration> for resource <id> (execution id: <id>) — a scheduled step has been queued to run after the specified duration.\nStep execution\nAs steps are executed, the engine logs their progress:\nRunning step <step> on resource <id> (execution id: <id>) — a step is about to be executed.\nStep <step> completed successfully (execution id: <id>) — the step finished without errors.\nWorkflow '<name>' completed for resource <id> (execution id: <id>) — all steps in the workflow have been executed.\nStep failures and timeouts\nWhen a step fails or the executor times out, the engine logs the error and fires a step failed event. The step will be retried in the next execution cycle (see Handling failures for more details).\nStep <step> failed (execution id: <id>) - error message: <message> — the step threw an exception during execution.\nWorkflow executor timed out during execution of step <step> — runtime exception indicating that the step exceeded the configured executor task timeout. See Understanding the workflows engine for"},
  {"id": "_workflow_security_considerations_", "title": "Security considerations", "breadcrumb": ["Managing workflows"], "url": "index.html#_workflow_security_considerations_", "md": "md/_workflow_security_considerations_.md", "text": "When designing workflows, it is important to understand the trust boundaries between the event that triggers a workflow, the conditions that control whether it runs, and the steps it executes. A misconfigured workflow can allow users to trigger privileged actions on themselves without administrator involvement.\nThis section is particularly relevant when self-registration is enabled in the realm.\nAttribute-based conditions and privileged steps\nConditions such as has-user-attribute evaluate attributes stored on the user. Steps such as grant-role and join-group perform privileged actions on the same user. When these are combined, the security of the workflow depends entirely on who can write the attribute that the condition checks.\nConsider the following workflow:\nname: Onboarding gold members\non: user-created\nif: has-user-attribute(membership=gold)\nsteps:\n  - uses: grant-role\n    with:\n      role: gold-member\nIf the membership attribute is writable by end users - for example, through a registration form - then a self-registering user can set membership=gold, satisfy the condition, and receive the gold-member role without any administrator review.\nTo use this workflow safely, the membership attribute must be configured so that only administrators can write to it. There are two aspects to consider: managed vs. unmanaged attributes, and attribute write permissions.\nUnmanaged attributes\nWhen the Unmanaged Attributes policy in the realm settings is set to Enabled, Keycloak persists any attribute submitted during registration, even if the attribute is not defined in the user profile configuration. This means a self-registering user can supply arbitrary attribute names and values that may satisfy a workflow condition.\nTo prevent this, avoid setting the Unmanaged Attributes policy to Enabled. Prefer Disabled (the default) or Admin can edit, which restrict unmanaged attribute handling to the administrative context.\nManaged attribute write permissions\nEven when unmanaged"},
  {"id": "_understanding_common_use_cases_", "title": "Understanding common use cases", "breadcrumb": ["Managing workflows"], "url": "index.html#_understanding_common_use_cases_", "md": "md/_understanding_common_use_cases_.md", "text": "Workflows can be used to automate a wide range of administrative tasks within a realm. Here are some common use cases where workflows can be particularly beneficial:\nUser Onboarding\nWhen a new user is created, a workflow can automatically send a welcome email, and assign initial roles or groups to the user. This ensures that new users have the necessary access and information from the moment they join.\nname: Onboarding gold members\non: user-created\nif: has-user-attribute(membership=gold)\nsteps:\n  - uses: notify-user\n    with:\n      message: \"Welcome to the Gold Membership program!\"\n  - uses: grant-role\n    with:\n      role: gold-member\nWhen using attribute-based conditions with privileged steps like grant-role or join-group, ensure the attribute is not writable by end users. See Security considerations for details.\nUser Offboarding\nWhen a user is removed from a specific group, a workflow can automatically revoke certain roles or permissions associated with that group.\nname: Offboarding sales members\non: user-group-membership-removed(/Sales)\nsteps:\n  - uses: revoke-role\n    with:\n      role:\n        - sales-rep\n        - manager\n        - sales-intern\nTracking user activity and taking actions on inactivity\nWhen a user has been inactive for a certain period, a workflow can send reminder emails and deactivate the account.\nname: Track inactive users\non: user-authenticated\nschedule:\n  after: 5s\n  batch-size: 2\nconcurrency:\n  restart-in-progress: true\nsteps:\n  - uses: notify-user\n    after: 180d\n    with:\n      message: It has been a while since your last login. We miss you!\n  - uses: notify-user\n    after: 60d\n    with:\n      message: Your account will be disabled in ${workflow.daysUntilNextStep} days!\n  - uses: disable-user\n    after: 7d\n  - uses: notify-user\n    with:\n      message: Your account was disabled. Sorry to see you go."},
  {"id": "_managing_scim", "title": "Managing users and groups through SCIM", "breadcrumb": [], "url": "index.html#_managing_scim", "md": "md/_managing_scim.md", "text": "SCIM (System for Cross-domain Identity Management) is a standard protocol designed to simplify identity management across multiple systems and domains. Defined by RFC 7643 (Core Schema) and RFC 7644 (Protocol), SCIM provides a common set of REST APIs and schemas for creating, reading, updating, and deleting identity resources such as users and groups. By adopting SCIM, organizations can automate user provisioning and deprovisioning across their identity infrastructure using widely supported tooling and libraries.\nKeycloak supports SCIM APIs for managing users and groups within a realm. External systems such as identity governance platforms, HR systems, or other identity providers can use these standardized APIs to provision and manage users in Keycloak without relying on the proprietary Admin REST API.\nIn the current release, the SCIM implementation covers:\nUser management: Create, read, update, patch, and delete user resources.\nGroup management: Create, read, update, patch, and delete group resources, including membership management.\nFiltering and pagination: Search resources using SCIM filter expressions with support for pagination, subject to the constraints described in Filtering resources.\nSchema extensions: Support for the Enterprise User extension (RFC 7643, Section 4.3) and custom schema extensions through User Profile attribute mapping.\nSchema discovery: Endpoints for discovering supported schemas, resource types, and server capabilities.\nThe SCIM API is based on the same underlying user and group management functionality as the Admin REST API, ensuring consistency in behavior and permissions. However, the SCIM API provides a standardized interface that can be easily integrated with third-party tools and platforms that support SCIM."},
  {"id": "_enabling_scim_", "title": "Enabling SCIM for a realm", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_enabling_scim_", "md": "md/_enabling_scim_.md", "text": "Once the feature is enabled on the server, you must also enable SCIM for each realm individually. This can be done through the Admin Console or the Admin REST API.\nUsing the Admin Console\nProcedure\nClick Realm settings in the menu.\nOn the General tab, locate the SCIM API toggle.\nSet the toggle to On.\nClick Save.\nEnabling SCIM API in realm settings\nObtaining the SCIM API base URL\nThe SCIM API in Keycloak is exposed under the following base URL:\nhttp://<host>:<port>/realms/<realm-name>/scim/v2\nThis base URL is used to construct the full URLs for the available SCIM endpoints:\n/ServiceProviderConfig\n/ResourceTypes\n/Schemas\n/Users\n/Groups\nThe SCIM API requires a bearer token with the appropriate permissions. See Authorizing access to SCIM endpoints for details on how to set up a client and obtain an access token."},
  {"id": "_scim_accessing_endpoints_", "title": "Accessing the SCIM endpoints", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_accessing_endpoints_", "md": "md/_scim_accessing_endpoints_.md", "text": "All SCIM endpoints require authorization using an OAuth 2.0 Bearer Token.\nUnauthorized requests receive a 401 Unauthorized response. The bearer token must also have the appropriate permissions to perform the requested operation.\nOnly confidential clients can access the SCIM endpoints. Public clients are not supported for SCIM API calls.\nSetting up a service account client\nTo access the SCIM APIs programmatically, you typically create a confidential client with a service account in Keycloak. This client obtains access tokens using the client credentials grant.\nProcedure\nClick Clients in the menu and then click Create client.\nSet the Client ID (for example, scim-client) and click Next.\nEnable Client authentication and Service accounts roles, then click Save.\nOn the Credentials tab, note the Client secret.\nAssigning permissions\nThe service account associated with the client must be granted the appropriate realm management roles to access SCIM resources. The required roles depend on the operations the client needs to perform.\nThe Full Scope Allowed switch is deprecated and will be removed in a future release. Do not enable it on the SCIM client. Instead, explicitly configure the required role scope mappings as described below. See Role scope mappings for details.\nProcedure\nClick Clients in the menu, then select the client you created.\nClick the Client scopes tab, select the dedicated client scope for the client (for example, scim-client-dedicated), then click the Scope tab.\nSet Full Scope Allowed to Off.\nClick Assign role, then filter by clients and select the realm-management client.\nAssign the required roles based on the operations the client needs to perform. This adds the roles to the client’s role scope mappings.\nClick the Service account roles tab.\nClick Assign role, then filter by clients and select the realm-management client.\nAssign the same roles assigned in the previous step.\nRoles included in the access token are the intersection of the client’s role"},
  {"id": "_scim_admin_resource_protection_", "title": "Protection of administrative resources", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_admin_resource_protection_", "md": "md/_scim_admin_resource_protection_.md", "text": "Keycloak automatically protects administrative users and groups from being modified through the SCIM API. This prevents external identity providers or SCIM clients from accidentally or maliciously altering accounts and groups that have administrative privileges in the realm.\nWhy this protection exists\nThe SCIM API is designed for automated user and group synchronization with external identity providers. Because SCIM clients typically operate with broad management permissions, a compromised or misconfigured client could otherwise:\nDelete or disable administrator accounts, locking out realm management.\nModify administrator credentials or attributes.\nAdd unauthorized users to groups that carry administrative roles, escalating their privileges.\nRemove administrators from their groups, revoking their access.\nTo prevent these scenarios, Keycloak ensures that administrative resources can only be managed through the Admin Console or the Admin REST API, never through SCIM.\nProtected admin users\nA user is considered an administrative user if they hold any administrative role. This includes roles from the realm-management client, roles from the master realm administration clients (such as <realm-name>-realm), and administrative realm roles on the master realm (such as admin or create-realm). Roles may be assigned directly to the user, inherited through group membership, or obtained through composite roles.\nThe following restrictions apply to administrative users accessed through the SCIM API:\nRead operations (GET) return a minimal representation containing only the id, schemas, and userName attributes. Personal details such as name and emails are not included.\nWrite operations (PUT, PATCH, DELETE) return a 403 Forbidden response.\nAdministrative users still appear in listing and search results, but always with the minimal representation.\nOnce all administrative roles are revoked from a user, the user becomes fully manageable through SCIM again.\nProtected admin groups\nA group is"},
  {"id": "_understanding_scim_endpoints_", "title": "Understanding the SCIM endpoints", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_understanding_scim_endpoints_", "md": "md/_understanding_scim_endpoints_.md", "text": "All SCIM endpoints use the application/scim+json content type for both requests and responses, as specified by RFC 7644. The application/json content type is also accepted for requests.\nAvailable endpoints\nThe following table summarizes all available and supported SCIM endpoints.\nEndpoint Methods Description\n/Users\nGET, POST\nList all users or create a new user.\n/Users/{id}\nGET, PUT, PATCH, DELETE\nRetrieve, replace, partially update, or delete a specific user.\n/Users/.search\nPOST\nSearch users using a request body (useful for complex or long filter expressions).\n/Groups\nGET, POST\nList all groups or create a new group.\n/Groups/{id}\nGET, PUT, PATCH, DELETE\nRetrieve, replace, partially update, or delete a specific group.\n/Groups/.search\nPOST\nSearch groups using a request body.\n/ServiceProviderConfig\nGET\nRetrieve the SCIM capabilities supported by the server.\n/ResourceTypes\nGET\nList the resource types (User, Group) available on the server.\n/Schemas\nGET\nList all SCIM schemas supported by the server, including extensions.\n/Schemas/{id}\nGET\nRetrieve a specific schema by its ID (URN).\nHTTP methods\nThe SCIM API supports the following HTTP methods for resource management:\nMethod Status Code Description\nPOST\n201 Created\nCreate a new resource.\nGET\n200 OK\nRetrieve a single resource by ID, or list/search resources.\nPUT\n200 OK\nReplace an existing resource entirely.\nPATCH\n200 OK\nPartially modify a resource using add, replace, or remove operations.\nDELETE\n204 No Content\nDelete a resource.\nQuery parameters\nThe following query parameters can be used with GET requests to control the response. The same parameters are also accepted in the body of POST /.search requests.\nParameter Type Description\nfilter\nString\nA SCIM filter expression to search for resources. See Filtering resources.\nstartIndex\nInteger\nThe 1-based index of the first result to return. Defaults to 1.\ncount\nInteger\nThe maximum number of results to return per page.\nattributes\nString\nA comma-separated list of attribute names to"},
  {"id": "_accessing_scim_service_provider_config_", "title": "Accessing the SCIM service provider configuration", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_accessing_scim_service_provider_config_", "md": "md/_accessing_scim_service_provider_config_.md", "text": "As per the SCIM specification, the Service Provider Configuration endpoint (/ServiceProviderConfig) provides metadata about the capabilities available from the SCIM API.\ncurl http://localhost:8080/realms/myrealm/scim/v2/ServiceProviderConfig \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Accept: application/scim+json\"\nA successful response returns the capabilities of the SCIM API, including supported operations such as patch, filter, and the authentication schemes:\n{\n  \"schemas\": [\"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig\"],\n  \"patch\": {\n    \"supported\": true\n  },\n  \"bulk\": {\n    \"supported\": false,\n    \"maxOperations\": 0,\n    \"maxPayloadSize\": 0\n  },\n  \"filter\": {\n    \"supported\": true,\n    \"maxResults\": 100\n  },\n  \"changePassword\": {\n    \"supported\": false\n  },\n  \"sort\": {\n    \"supported\": false\n  },\n  \"etag\": {\n    \"supported\": false\n  },\n  \"authenticationSchemes\": [\n    {\n      \"type\": \"oauthbearertoken\",\n      \"name\": \"OAuth Bearer Token\",\n      \"description\": \"Authentication scheme using the OAuth Bearer Token standard\"\n    }\n  ]\n}\nAt the moment, the Service Provider Configuration is read-only and cannot be modified.\nSupported and unsupported capabilities\nThe Service Provider Configuration reflects the capabilities implemented by Keycloak. The following optional capabilities defined by RFC 7644 are not supported in this release:\nBulk operations (bulk.supported is false). There is no /Bulk endpoint; send one request per resource.\nSorting (sort.supported is false). The sortBy and sortOrder parameters are accepted but ignored, and resources are returned in the default order of the underlying store.\nETag / resource versioning (etag.supported is false). Resources do not carry a meta.version, and conditional requests such as If-Match are not honored.\nPassword changes (changePassword.supported is false). The password attribute cannot be set or updated through SCIM. Manage credentials through the Admin Console or the Admin REST API instead."},
  {"id": "_scim_managing_users_", "title": "Managing users", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_managing_users_", "md": "md/_scim_managing_users_.md", "text": "The SCIM /Users endpoint allows you to create, read, update, and delete realm user resources in Keycloak. User resources conform to the urn:ietf:params:scim:schemas:core:2.0:User schema as defined in RFC 7643.\nCore user attributes\nThe following table shows the core SCIM user attributes and how they map to Keycloak user attributes:\nSCIM Attribute Keycloak Attribute Description\nuserName\nusername\nUnique identifier for the user. Required.\nname.givenName\nfirstName\nGiven name (first name).\nname.familyName\nlastName\nFamily name (last name).\nemails\nemail\nUser email addresses. Even though the attribute is multi-valued, Keycloak does not support mutiple emails for a given user account. When multiple email values are submitted, only the first value is persisted. In SCIM responses, the stored address is returned as a single work email entry that is marked as primary.\nactive\nenabled\nWhether the user account is enabled.\nlocale\nlocale\nUser locale. Only available when internationalization is enabled on the realm.\nexternalId\n(custom attribute)\nAn identifier from an external system. Requires user profile configuration. See Mapping attributes.\nAdditional name sub-attributes (name.middleName, name.honorificPrefix, name.honorificSuffix) can be mapped by configuring user profile attributes. See Mapping attributes for details.\nCreating a user\nTo create a user, send a POST request to the /Users endpoint. At minimum, you must provide a userName:\ncurl -X POST http://localhost:8080/realms/myrealm/scim/v2/Users \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/scim+json\" \\\n  -d '{\n    \"schemas\": [\"urn:ietf:params:scim:schemas:core:2.0:User\"],\n    \"userName\": \"jdoe\",\n    \"name\": {\n      \"givenName\": \"John\",\n      \"familyName\": \"Doe\"\n    },\n    \"emails\": [\n      {\n        \"value\": \"jdoe@example.com\",\n        \"type\": \"work\",\n        \"primary\": true\n      }\n    ],\n    \"active\": true\n  }'\nA successful response returns the created user with a 201 Created status:\n{"},
  {"id": "_scim_managing_groups_", "title": "Managing groups", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_managing_groups_", "md": "md/_scim_managing_groups_.md", "text": "The SCIM /Groups endpoint allows you to create, read, update, and delete realm group resources in Keycloak. Group resources conform to the urn:ietf:params:scim:schemas:core:2.0:Group schema as defined in RFC 7643.\nGroup attributes\nSCIM Attribute Keycloak Attribute Description\ndisplayName\nname\nThe name of the group. Required.\nexternalId\n(custom attribute)\nAn identifier from an external system.\nmembers\n(group membership)\nList of users that belong to this group. Read-only on GET; managed via PATCH.\nCreating a group\nTo create a group, send a POST request to the /Groups endpoint:\ncurl -X POST http://localhost:8080/realms/myrealm/scim/v2/Groups \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/scim+json\" \\\n  -d '{\n    \"schemas\": [\"urn:ietf:params:scim:schemas:core:2.0:Group\"],\n    \"displayName\": \"Engineering Team\",\n    \"externalId\": \"eng-team-001\"\n  }'\nA successful response returns the created group with a 201 Created status.\nGroup members cannot be specified during group creation. Attempting to include members in the POST request results in a 400 Bad Request error. Use the PATCH method to add members after creating the group.\nIf a group with the same displayName already exists, the API returns a 409 Conflict response with scimType: \"uniqueness\".\nRetrieving a group\nTo retrieve a group by ID:\ncurl http://localhost:8080/realms/myrealm/scim/v2/Groups/{id} \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Accept: application/scim+json\"\nListing groups\nTo list all groups in the realm:\ncurl http://localhost:8080/realms/myrealm/scim/v2/Groups \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Accept: application/scim+json\"\nFor filtering and pagination of results, see Filtering resources.\nUpdating a group\nTo replace a group’s attributes, send a PUT request:\ncurl -X PUT http://localhost:8080/realms/myrealm/scim/v2/Groups/{id} \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/scim+json\" \\\n  -d '{\n    \"schemas\":"},
  {"id": "_scim_filtering_resources", "title": "Filtering resources", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_filtering_resources", "md": "md/_scim_filtering_resources.md", "text": "The SCIM API in Keycloak supports the full filter syntax defined in RFC 7644, Section 3.4.2.2, allowing you to search for resources using a rich expression language.\nUsing filters\nFilters are specified using the filter query parameter on GET requests:\ncurl \"http://localhost:8080/realms/myrealm/scim/v2/Users?filter=userName+eq+\\\"jdoe\\\"\" \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Accept: application/scim+json\"\nFilter values must be URL-encoded when used in query parameters. Spaces in the filter expression should be encoded as + or %20. The examples in this section show the raw filter syntax for readability.\nComparison operators\nThe following comparison operators are supported:\nOperator Description Example\neq\nEqual\nuserName eq \"jdoe\"\nne\nNot equal\nactive ne false\nco\nContains\nemails co \"example.com\"\nsw\nStarts with\nuserName sw \"j\"\new\nEnds with\nuserName ew \"doe\"\ngt\nGreater than\nmeta.created gt \"2025-01-01T00:00:00Z\"\nge\nGreater than or equal\nmeta.created ge \"2025-01-01T00:00:00Z\"\nlt\nLess than\nmeta.lastModified lt \"2025-06-01T00:00:00Z\"\nle\nLess than or equal\nmeta.lastModified le \"2025-06-01T00:00:00Z\"\npr\nPresent (attribute has a value)\nemails.value pr\nThe gt, ge, lt, and le operators are supported on date/time attributes such as meta.created and meta.lastModified. The sw, ew, and co operators are supported on string attributes but not on date/time or boolean attributes. Invalid operator/type combinations return a 400 Bad Request response with scimType: \"invalidFilter\".\nAttributes without a value\nA comparison such as attribute eq \"value\" or attribute ne \"value\" does not match resources where the attribute has no value. Use not (attribute pr) to find them. For a multi-valued attribute, attribute ne \"value\" matches resources that have at least one other value.\nThe eq and ne operators accept the null literal, but the comparison never matches, so it cannot be used to find resources without a value.\nLogical operators\nFilters can be combined using logical operators:"},
  {"id": "_scim_mapping_attributes_", "title": "Mapping user attributes to SCIM schemas", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_mapping_attributes_", "md": "md/_scim_mapping_attributes_.md", "text": "Keycloak uses the User Profile configuration to define how user attributes are mapped to SCIM schema attributes. A set of core attributes are mapped by default, and additional attributes can be mapped by configuring user profile attributes with a SCIM schema attribute mapping.\nDefault attribute mappings\nThe following attributes are automatically mapped to the SCIM core user schema (urn:ietf:params:scim:schemas:core:2.0:User) without any additional configuration:\nKeycloak Attribute SCIM Attribute\nusername\nuserName\nemail\nemails\nfirstName\nname.givenName\nlastName\nname.familyName\nenabled\nactive\ncreatedTimestamp\nmeta.created\nlocale\nlocale (only when internationalization is enabled)\nSupported core multivalued and complex attributes\nRFC 7643, Section 4.1.2 defines a set of multivalued attributes for the core User schema (urn:ietf:params:scim:schemas:core:2.0:User). Keycloak supports a subset of these attributes natively. The following table lists the core multivalued and complex attributes and their support status:\nSCIM Attribute Supported Notes\nemails\nYes\nExposed as a multivalued attribute, but backed by the single Keycloak email attribute. Only the first value is stored and returned. See Managing users for details.\ngroups\nYes\nReflects the user’s group memberships. Group memberships can be set during user creation and managed through PATCH operations on the user resource. See Managing users for details. Group membership can also be managed from the group side using group PATCH operations. See Managing groups for details.\nname\nYes\nA single complex attribute. Its sub-attributes are mapped from user profile attributes. See Mapping additional name attributes.\nphoneNumbers, ims, photos, entitlements, roles, x509Certificates\nNo\nNot defined in the Keycloak core User schema. You cannot map a user profile attribute to these attributes under the core schema URN. To expose equivalent data, use a schema extension or a custom multivalued mapping instead. See Mapping multivalued"},
  {"id": "_scim_managing_schema_extensions_", "title": "Managing schema extensions", "breadcrumb": ["Managing users and groups through SCIM"], "url": "index.html#_scim_managing_schema_extensions_", "md": "md/_scim_managing_schema_extensions_.md", "text": "In addition to the core SCIM user and group schemas, Keycloak supports schema extensions that allow you to expose additional attributes through the SCIM API. Extension schemas are configured using the same User Profile SCIM attribute mapping described in Mapping user attributes to SCIM schemas, but with URN-prefixed values that identify which extension schema the attribute belongs to. All configured extension schemas are automatically discoverable through the /Schemas endpoint.\nEnterprise User extension\nThe Enterprise User extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) is defined in RFC 7643, Section 4.3 and provides attributes commonly used in enterprise environments.\nAvailable attributes\nAttribute Description\nemployeeNumber\nThe employee’s number or identifier.\ncostCenter\nThe cost center to which the user belongs.\norganization\nThe name of the organization.\ndivision\nThe name of the division.\ndepartment\nThe name of the department.\nmanager\nThe user’s manager, with sub-attributes value (manager identifier) and displayName.\nEnabling the enterprise extension\nTo use the Enterprise User extension, you must configure user profile attributes for each enterprise attribute you want to expose. Each attribute must have a SCIM attribute mapping pointing to the enterprise schema attribute.\nIn the Admin Console, when creating or editing a user profile attribute, the SCIM section provides the Enterprise User schema attributes as selectable options. Alternatively, you can type the full URN-prefixed value manually.\nFor example, to enable the employeeNumber and department attributes, create two user profile attributes:\nUser Profile Attribute Name SCIM Attribute Value\nemployeeNumber\nurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber\ndepartment\nurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department\nFor complex attributes like manager, you map individual sub-attributes:\nUser Profile Attribute Name SCIM Attribute Value"},
  {"id": "assembly-managing-clients_server_administration_guide", "title": "Managing OpenID Connect and SAML Clients", "breadcrumb": [], "url": "index.html#assembly-managing-clients_server_administration_guide", "md": "md/assembly-managing-clients_server_administration_guide.md", "text": "Clients are entities that can request authentication of a user. Clients come in two forms. The first type of client is an application that wants to participate in single sign-on. These clients just want Keycloak to provide security for them. The other type of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user. This section discusses various aspects around configuring clients and various ways to do it."},
  {"id": "_oidc_clients", "title": "Managing OpenID Connect clients", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#_oidc_clients", "md": "md/_oidc_clients.md", "text": "OpenID Connect is the recommended protocol to secure applications. It was designed from the ground up to be web friendly and it works best with HTML5/JavaScript applications.\nCreating an OpenID Connect client\nTo protect an application that uses the OpenID connect protocol, you create a client.\nProcedure\nClick Clients in the menu.\nClick Create client.\nCreate client\nLeave Client type set to OpenID Connect.\nEnter a Client ID.\nThis ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.\nSupply a Name for the client.\nIf you plan to localize this name, set up a replacement string value. For example, a string value such as ${myapp}. See the Server Developer Guide for more information.\nClick Save.\nThis action creates the client and bring you to the Settings tab, where you can perform Basic configuration.\nBasic configuration\nThe Settings tab includes many options to configure this client.\nSettings tab\nGeneral Settings\nClient ID\nThe alphanumeric ID string that is used in OIDC requests and in the Keycloak database to identify the client.\nName\nThe name for the client in Keycloak UI screen. To localize the name, set up a replacement string value. For example, a string value such as ${myapp}. See the Server Developer Guide for more information.\nDescription\nThe description of the client. This setting can also be localized.\nAlways Display in Console\nAlways list this client in the Account Console even if this user does not have an active session.\nAccess Settings\nRoot URL\nIf Keycloak uses any configured relative URLs, this value is prepended to them.\nHome URL\nProvides the default URL for when the auth server needs to redirect or link back to the client.\nValid Redirect URIs\nRequired field. Enter a URL pattern and click + to add and - to remove existing URLs and click Save. Exact (case sensitive) string matching is used to compare valid redirect URIs.\nYou can use wildcards at the end of the URL pattern. For example"},
  {"id": "_client-saml-configuration", "title": "Creating a SAML client", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#_client-saml-configuration", "md": "md/_client-saml-configuration.md", "text": "Keycloak supports SAML 2.0 for registered applications. POST and Redirect bindings are supported. You can choose to require client signature validation. You can have the server sign and/or encrypt responses as well.\nProcedure\nClick Clients in the menu.\nClick Create client to go to the Create client page.\nSet Client type to SAML.\nCreate client\nEnter the Client ID of the client. This is often a URL and is the expected issuer value in SAML requests sent by the application.\nClick Save. This action creates the client and brings you to the Settings tab.\nThe following sections describe each setting on this tab.\nSettings tab\nThe Settings tab includes many options to configure this client.\nClient settings\nGeneral settings\nClient ID\nThe alphanumeric ID string that is used in OIDC requests and in the Keycloak database to identify the client. This value must match the issuer value sent with AuthNRequests. Keycloak pulls the issuer from the Authn SAML request and match it to a client by this value.\nName\nThe name for the client in a Keycloak UI screen. To localize the name, set up a replacement string value. For example, a string value such as ${myapp}. See the Server Developer Guide for more information.\nDescription\nThe description of the client. This setting can also be localized.\nAlways Display in Console\nAlways list this client in the Account Console even if this user does not have an active session.\nAccess Settings\nRoot URL\nWhen Keycloak uses a configured relative URL, this value is prepended to the URL.\nHome URL\nIf Keycloak needs to link to a client, this URL is used.\nValid Redirect URIs\nEnter a URL pattern and click the + sign to add. Click the - sign to remove. Click Save to save these changes. Wildcards values are allowed only at the end of a URL. For example, http://host.com/*$$. This field is used when the exact SAML endpoints are not registered and Keycloak pulls the Assertion Consumer URL from a request.\nIDP-Initiated SSO URL name\nURL fragment name to reference"},
  {"id": "con-client-links_server_administration_guide", "title": "Client links", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#con-client-links_server_administration_guide", "md": "md/con-client-links_server_administration_guide.md", "text": "To link from one client to another, Keycloak provides a redirect endpoint: /realms/realm_name/clients/{client-id}/redirect.\nIf a client accesses this endpoint using a HTTP GET request, Keycloak returns the configured base URL for the provided Client and Realm in the form of an HTTP 307 (Temporary Redirect) in the response’s Location header. As a result of this, a client needs only to know the Realm name and the Client ID to link to them. This indirection avoids hard-coding client base URLs.\nAs an example, given the realm master and the client-id account:\nhttp://host:port/realms/master/clients/account/redirect\nThis URL temporarily redirects to: http://host:port/realms/master/account"},
  {"id": "_protocol-mappers", "title": "OIDC token and SAML assertion mappings", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#_protocol-mappers", "md": "md/_protocol-mappers.md", "text": "Applications receiving ID tokens, access tokens, or SAML assertions may require different roles and user metadata.\nYou can use Keycloak to:\nHardcode roles, claims and custom attributes.\nPull user metadata into a token or assertion.\nRename roles.\nYou perform these actions in the Mappers tab in the Admin Console.\nMappers tab\nNew clients do not have built-in mappers, but they can inherit some mappers from client scopes. See the client scopes section for more details.\nProtocol mappers map items (such as an email address, for example) to a specific claim in the identity and access token. The function of a mapper should be self-explanatory from its name. You add pre-configured mappers by clicking Add Builtin.\nEach mapper has a set of common settings. Additional settings are available, depending on the mapper type. Click Edit next to a mapper to access the configuration screen to adjust these settings.\nMapper config\nDetails on each option can be viewed by hovering over its tooltip.\nYou can use most OIDC mappers to control where the claim gets placed. You opt to include or exclude the claim from the id and access tokens by adjusting the Add to ID token and Add to access token switches.\nYou can add mapper types as follows:\nProcedure\nGo to the Mappers tab.\nClick Configure a new mapper.\nAdd mapper\nSelect a Mapper Type from the list box.\nPriority order\nMapper implementations have priority order. Priority order is not the configuration property of the mapper. It is the property of the concrete implementation of the mapper.\nMappers are sorted by the order in the list of mappers. The changes in the token or assertion are applied in that order with the lowest applying first. Therefore, the implementations that are dependent on other implementations are processed in the necessary order.\nFor example, to compute the roles which will be included with a token:\nResolve audiences based on those roles.\nProcess a JavaScript script that uses the roles and audiences already available in the"},
  {"id": "_client_installation", "title": "Generating client adapter config", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#_client_installation", "md": "md/_client_installation.md", "text": "Keycloak can generate configuration files that you can use to install a client adapter in your application’s deployment environment. A number of adapter types are supported for OIDC and SAML.\nClick on the Action menu and select the Download adapter config option\nSelect the Format Option you want configuration generated for.\nAll Keycloak client adapters for OIDC and SAML are supported. The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files."},
  {"id": "_client_scopes", "title": "Client scopes", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#_client_scopes", "md": "md/_client_scopes.md", "text": "Use Keycloak to define a shared client configuration in an entity called a client scope. A client scope configures protocol mappers and role scope mappings for multiple clients.\nClient scopes also support the OAuth 2 scope parameter. Client applications use this parameter to request claims or roles in the access token, depending on the requirement of the application.\nTo create a client scope, follow these steps:\nClick Client Scopes in the menu.\nClient scopes list\nClick Create.\nName your client scope.\nClick Save.\nA client scope has similar tabs to regular clients. You can define protocol mappers and role scope mappings. These mappings can be inherited by other clients and are configured to inherit from this client scope.\nProtocol\nWhen you create a client scope, choose the Protocol. Clients linked in the same scope must have the same protocol.\nEach realm has a set of pre-defined built-in client scopes in the menu.\nSAML protocol: The role_list. This scope contains one protocol mapper for the roles list in the SAML assertion.\nOpenID Connect protocol: Several client scopes are available:\nroles\nThis scope is not defined in the OpenID Connect specification and is not added automatically to the scope claim in the access token. This scope has mappers, which are used to add the roles of the user to the access token and add audiences for clients that have at least one client role. These mappers are described in more detail in the Token Role mappings section and Audience section.\nweb-origins\nThis scope is also not defined in the OpenID Connect specification and not added to the scope claiming the access token. This scope is used to add allowed web origins to the access token allowed-origins claim.\nmicroprofile-jwt\nThis scope handles claims defined in the MicroProfile/JWT Auth Specification. This scope defines a user property mapper for the upn claim and a realm role mapper for the groups claim. These mappers can be changed so different properties can be used to create the"},
  {"id": "_client_policies", "title": "Client Policies", "breadcrumb": ["Managing OpenID Connect and SAML Clients"], "url": "index.html#_client_policies", "md": "md/_client_policies.md", "text": "To make it easy to secure client applications, it is beneficial to realize the following points in a unified way.\nSetting policies on what configuration a client can have\nValidation of client configurations\nConformance to a required security standards and profiles such as Financial-grade API (FAPI) and OAuth 2.1\nTo realize these points in a unified way, Client Policies concept is introduced.\nClient Policies are evaluated for protocol mapper create, update, and delete operations on clients through the Admin REST API. They are not evaluated for protocol mapper operations on client scopes.\nUse-cases\nClient Policies realize the following points mentioned as follows.\nSetting policies on what configuration a client can have\nConfiguration settings on the client can be enforced by client policies during client creation/update, but also during OpenID Connect requests to Keycloak server, which are related to particular client. Keycloak supports similar thing also through the Client Registration Policies described in the Client registration service in the Securing applications and Services guide. However, Client Registration Policies can only cover OIDC Dynamic Client Registration. Client Policies cover not only what Client Registration Policies can do, but other client registration and configuration ways. The current plans are for Client Registration to be replaced by Client Policies.\nValidation of client configurations\nKeycloak supports validation whether the client follows settings like Proof Key for Code Exchange, Request Object Signing Algorithm, Holder-of-Key Token, and so on some endpoints like Authorization Endpoint, Token Endpoint, and so on. These can be specified by each setting item (on Admin Console, switch, pull-down menu and so on). To make the client application secure, the administrator needs to set many settings in the appropriate way, which makes it difficult for the administrator to secure the client application. Client Policies can do these validation of"},
  {"id": "_oid4vci", "title": "Configuring Keycloak as a Verifiable Credential Issuer", "breadcrumb": [], "url": "index.html#_oid4vci", "md": "md/_oid4vci.md", "text": "This feature is in preview and is not fully supported. It is disabled by default and can be enabled with --features=oid4vc-vci. Alternatively, users who explicitly want to enable the full preview feature set can use --features=preview. Backward compatibility is not guaranteed, and future updates may introduce breaking changes.\nKeycloak supports the OpenID for Verifiable Credential Issuance (OpenID4VCI) protocol, enabling it to act as a credential issuer in decentralized identity ecosystems. With this protocol, you can issue digitally signed Verifiable Credentials (VCs) that relying parties (verifiers) can independently verify without contacting Keycloak.\nThis chapter explains what Verifiable Credentials are, how the protocol works, and walks you through every step needed to configure Keycloak for credential issuance."},
  {"id": "what-are-verifiable-credentials", "title": "What are Verifiable Credentials?", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#what-are-verifiable-credentials", "md": "md/what-are-verifiable-credentials.md", "text": "Verifiable Credentials are the digital equivalent of physical credentials like passports, driver’s licenses, or university degrees. They are cryptographically signed, tamper-evident data structures containing claims about an entity (a person, organization, or device). The key properties of VCs:\nTamper-evident: Any alteration invalidates the cryptographic signature.\nPrivacy-preserving: Support selective disclosure (e.g., prove you are over 18 without revealing your exact birthdate).\nOffline-verifiable: A verifier can check the credential’s validity without contacting the issuer.\nHolder-controlled: The individual receiving the credential controls when and with whom to share it.\nVerifiable Credential Formats\nOpenID4VCI supports multiple credential formats for encoding and issuing credentials:\nSD-JWT VC – Selective Disclosure JSON Web Token Verifiable Credential\nJWT VC – JSON Web Token Verifiable Credential\nmDL/mdoc – Mobile driver’s license / mobile document format\nKeycloak currently supports both SD-JWT VC and JWT VC for issuance. mDL/mdoc format has just experimental support in Keycloak and should not be used in production environments. It is planned for a proper support in the future releases."},
  {"id": "the-issuer-holder-verifier-model", "title": "The Issuer-Holder-Verifier Model", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#the-issuer-holder-verifier-model", "md": "md/the-issuer-holder-verifier-model.md", "text": "Verifiable Credentials rely on a trust model built around three distinct roles:\nFigure 2. Triangle of Trust — The Issuer-Holder-Verifier Model\nIssuer — The entity (in this case, Keycloak) that signs and issues credentials. Governed by OpenID4VCI.\nHolder — The individual or wallet that receives, stores, and presents credentials.\nVerifier — The relying party that validates the credential’s authenticity and integrity. Governed by OpenID4VP.\nAn important privacy property: the issuer and verifier never communicate directly. The holder controls what information to share and with whom. This means the issuer cannot track where, when, or how credentials are used."},
  {"id": "why-use-openid4vci", "title": "Why Use OpenID4VCI", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#why-use-openid4vci", "md": "md/why-use-openid4vci.md", "text": "OpenID4VCI brings verifiable credential issuance into the OpenID Connect ecosystem your organization already uses. Key benefits:\nInteroperability — Built on top of OAuth 2.0 and OpenID Connect, making it straightforward to integrate with existing identity infrastructure.\nPrivacy and security — Supports selective disclosure, key-bound credentials, and offline verification.\nRegulatory compliance — Aligns with frameworks like eIDAS 2.0 and emerging digital identity regulations worldwide.\nDeveloper efficiency — Leverages Keycloak’s existing authentication, authorization, and token management capabilities."},
  {"id": "real-world-applications", "title": "Real-World Applications", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#real-world-applications", "md": "md/real-world-applications.md", "text": "Verifiable Credentials open the door to a wide range of practical use cases:\nDigital identity cards or driver’s licenses issued by governments, where citizens reveal only what is needed (age, residency) for a given transaction.\nVerifiable diplomas and certificates issued by educational institutions, which employers can instantly verify without contacting the school.\nEmployee badges issued as VCs for secure office access and remote authentication.\nEvent tickets that are tamper-evident and verifiable offline.\nMembership credentials for professional associations, granting access to gated content or conference venues."},
  {"id": "how-credential-issuance-works-two-core-flows", "title": "How Credential Issuance Works: Two Core Flows", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#how-credential-issuance-works-two-core-flows", "md": "md/how-credential-issuance-works-two-core-flows.md", "text": "OpenID4VCI defines two primary ways to issue credentials. Which one to use depends on whether the user needs to authenticate interactively.\nAuthorization Code Flow\nThe Authorization Code Flow is an interactive flow where the holder must authenticate and explicitly consent to credential issuance. It is ideal when you need user approval before issuing a credential.\nThis flow reuses Keycloak’s standard OpenID Connect authorization endpoint, so no additional endpoint is needed for the authorization step. The wallet communicates through a registered OIDC client that must have OID4VCI enabled and the appropriate credential client scope assigned.\nHow it works:\nThe User wants a credential and initiates the process through their wallet.\nThe Wallet sends an Authorization Request to Keycloak’s Authorization Endpoint (via the registered OIDC Client).\nKeycloak prompts the User to log in and grant consent.\nThe User authenticates and approves the credential request.\nKeycloak returns an authorization code to the Wallet.\nThe Wallet exchanges the code at the Token Endpoint for an access token.\nThe Wallet requests the Verifiable Credential from the Credential Endpoint (/protocol/oid4vc/credential), presenting the access token.\nKeycloak validates the request, signs the credential, and returns it to the Wallet.\nFigure 3. Authorization Code Flow — Credential Issuance\nThis flow is best suited for scenarios where the user should be in control and give explicit permission for each credential issued.\nPre-Authorized Code Flow\nThe Pre-Authorized Code Flow is a non-interactive flow. The issuer creates a pre-approved credential offer, and the wallet can claim the credential without real-time user authentication. This is useful for bulk issuance, offline-capable scenarios, or when the user has already been authenticated through other means.\nPre-authorized credential offers can be created through the Keycloak Admin Console, the Admin REST API, or programmatically through a dedicated endpoint"},
  {"id": "what-this-chapter-covers", "title": "What This Chapter Covers", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#what-this-chapter-covers", "md": "md/what-this-chapter-covers.md", "text": "The rest of this chapter walks through the practical steps of configuring Keycloak as a Verifiable Credential Issuer.\nYou will learn how to:\nEnable the OID4VCI feature on your Keycloak server.\nCreate a dedicated realm for VC issuance.\nSet up users and cryptographic keys.\nDefine realm-level attributes that control credential behavior.\nCreate client scopes (each representing a credential type) with protocol mappers.\nRegister a client to handle credential requests.\nVerify the configuration by inspecting the issuer metadata endpoint."},
  {"id": "prerequisites", "title": "Prerequisites", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#prerequisites", "md": "md/prerequisites.md", "text": "Ensure the following requirements are met before proceeding:\nA running Keycloak server.\nThe OID4VCI feature flag enabled at startup.\nTo enable the feature, add the following flag to the startup command:\n--features=oid4vc-vci\nVerify the feature is active in the Keycloak Admin Console. Navigate to the master realm’s Dashboard, switch to the Server Info tab, and confirm that OID4VC_VCI appears under Enabled Features.\nFigure 5. OID4VC_VCI Feature in Server Info"},
  {"id": "configuring-credential-issuance-in-keycloak", "title": "Configuring Credential Issuance in Keycloak", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#configuring-credential-issuance-in-keycloak", "md": "md/configuring-credential-issuance-in-keycloak.md", "text": "In Keycloak, Verifiable Credentials are managed through ClientScopes, with each ClientScope representing a single Verifiable Credential type. To enable the issuance of a credential, the corresponding ClientScope must be assigned to an OpenID Connect client - ideally as optional.\nDuring the OAuth2 authorization process, the credential-specific scope can be requested by including the ClientScope’s name in the scope parameter of the authorization request. Once the user has successfully authenticated, the resulting Access Token MUST include the requested ClientScope in its scope claim. To ensure this, make sure the ClientScope option Include in token scope is enabled.\nWith this Access Token, the Verifiable Credential can be issued at the Credential Endpoint.\nBecause some configurations are not yet supported via the Admin Console, we may need to use the Keycloak Admin REST API to configure certain aspects. To interact with the Admin REST API, you first need to obtain a valid access token."},
  {"id": "authentication", "title": "Authentication", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#authentication", "md": "md/authentication.md", "text": "An access token is required to authenticate API requests.\nRefer to the following Keycloak documentation sections for detailed steps on:\nCreating a Client\nObtaining an Access Token"},
  {"id": "configuration-steps", "title": "Configuration Steps", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#configuration-steps", "md": "md/configuration-steps.md", "text": "Follow these steps to configure Keycloak as a Verifiable Credential Issuer. Each section is detailed with procedures, explanations, and examples where applicable."},
  {"id": "configuring-openid4vci-at-the-realm-level", "title": "Configuring OpenID4VCI at the Realm Level", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#configuring-openid4vci-at-the-realm-level", "md": "md/configuring-openid4vci-at-the-realm-level.md", "text": "The behavior of OID4VCI across the entire realm is determined by a combination of realm settings, cryptographic keys, and realm-level attributes. This section guides you through each step.\nCreating a Realm\nA realm in Keycloak is a logical container that manages users, clients, roles, and authentication flows. For Verifiable Credential (VC) issuance, create a dedicated realm to ensure isolation and maintain a clear separation of functionality.\nFor detailed instructions on creating a realm, refer to the Keycloak documentation: Creating a Realm.\nEnabling Verifiable Credentials for the Realm\nBefore configuring OID4VCI settings, you must enable Verifiable Credentials at the realm level:\nIn the Keycloak Admin Console, navigate to Realm Settings.\nOn the General tab, toggle the Verifiable Credentials switch On.\nFigure 6. Enabling Verifiable Credentials in Realm Settings\nThis enables the OID4VCI functionality for the realm. Once enabled, the OID4VC Issuer Metadata link appears in the Endpoints section of the General tab, and an OID4VCI Attributes section appears in the Tokens tab.\nKey Management Configuration\nCredentials are signed with a realm signing key. For SD-JWT VCs, the selected key must also provide an X.509 certificate chain that satisfies the HAIP issuer key resolution requirements:\nThe first certificate must be the leaf certificate for the credential signing key.\nThe leaf certificate must not be self-signed.\nAny intermediate certificates must follow the leaf certificate in chain order.\nThe trust anchor must not be included in the x5c JOSE header. If the configured chain ends with a self-signed root certificate, Keycloak removes it when creating the SD-JWT VC. Any non-self-signed trust anchor must be omitted from the configured chain.\nDo not use a generated realm key to sign SD-JWT VCs. A generated key either has no certificate or uses a self-signed certificate, so SD-JWT VC issuance fails. This restriction does not apply to JWT VCs.\nElliptic Curve cryptography"},
  {"id": "_oid4vci_user_setup", "title": "Creating a User Account", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_user_setup", "md": "md/_oid4vci_user_setup.md", "text": "A test user is required to simulate credential issuance and verify the setup.\nFor step-by-step instructions on creating a user, refer to the Keycloak documentation: Creating a User.\nEnsure that the user has a valid username, email, and password. If the password should not be reset upon first login, disable the \"Temporary\" toggle during password configuration.\nThe next step is to create verifiable credential for the user to indicate which verifiable credentials the particular user can request. You may switch to the tab Verifiable credentials of the user, request creating verifiable credential and create some verifiable credential for the user, which you want this user to be able to obtain. For now, you can choose some of the pre-defined OID4VCI credential scopes or some credential scope you created based on the instructions from the credential scope section.\nOnce verifiable credential is created, administrator can send credential offer to the user by email by click Send credential offer in the table of available verifiable credentials. This link is available in case user has email. It is also needed that SMTP is properly configured for the realm as described in the dedicated section. The email will also inform user that he has some verifiable credential available. User can also visit Account console and request issuance of some available verifiable credential by himself.\nCreating a verifiable credential for a user stores a snapshot of the user’s attributes with the credential entitlement. This snapshot does not freeze the values of claims mapped from user attributes. Keycloak reads the current user attributes when it issues or refreshes a credential. For details, see Understanding Attribute Snapshots and Credential Claims."},
  {"id": "_oid4vci_client_scope", "title": "Create Client Scopes with Mappers", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_client_scope", "md": "md/_oid4vci_client_scope.md", "text": "Client scopes define which user attributes are included in Verifiable Credentials (VCs) and therefore represent the Verifiable Credential configuration itself. Each credential type is configured as a dedicated client scope using the OpenID for Verifiable Credentials protocol.\nA client scope uses protocol mappers to map specific user attributes to claims within the credential. These protocol mappers also expose the corresponding metadata that is published through the Credential Issuer Metadata Endpoint.\nCreating a Client Scope via the Admin Console\nMany OID4VCI client scope attributes can be configured directly through the Keycloak Admin Console:\nNavigate to Client Scopes and click Create client scope.\nConfigure the basic settings:\nName – A unique identifier for this credential type (e.g., membership-credential).\nType – Select None (recommended for credential scopes).\nProtocol – Select OpenID for Verifiable Credentials.\nEnsure Include in token scope is toggled On — this is required for the scope to appear in the access token’s scope claim.\nEnsure Include in OpenID Provider Metadata is toggled On — when enabled, this client scope is included in the OpenID Provider Metadata and the credential configuration will be advertised in the Issuer Metadata Endpoint response.\nFigure 9. Creating an OID4VCI Client Scope\nAfter selecting the OID4VCI protocol, the following configuration fields become available:\nField Default Description\nCredential Configuration ID\n(scope name)\nIdentifier for this credential configuration. Exposed in the issuer metadata under credential_configurations_supported.\nCredential Identifier\n(scope name)\nIdentifier used during the credential issuance process.\nCredential Offer Required\nOff\nWhen enabled, a credential offer must be generated before issuance. Useful for pre-authorized code flows.\nIssuer DID\n(scope name)\nThe Decentralized Identifier (DID) of the issuer (e.g., did:web:vc.example.com).\nCredential Lifetime\n31536000 seconds (1 year)\nHow"},
  {"id": "create-and-configure-the-client", "title": "Create and Configure the Client", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#create-and-configure-the-client", "md": "md/create-and-configure-the-client.md", "text": "Set up a client to handle Verifiable Credential (VC) requests and assign the necessary scopes. The client does not differ from regular OpenID Connect clients — with one exception: it must have the appropriate optional ClientScopes assigned that define the Verifiable Credentials it is allowed to issue.\nAfter creating the client, you must configure its OID4VCI-specific settings.\nEnabling OID4VCI for the Client\nTo allow a client to issue Verifiable Credentials, you must enable OID4VCI for that specific client:\nIn the Keycloak Admin Console, navigate to Clients and select your client.\nGo to the Advanced tab.\nScroll down to the OpenID for Verifiable Credentials section.\nToggle OID4VCI enabled to On.\nClick Save.\nAssigning Credential Scopes\nFor a client to issue a specific type of credential, the corresponding OID4VCI client scope (which defines the credential format and claims) must be assigned to it:\nIn the Keycloak Admin Console, navigate to Clients and select your client.\nGo to the Client scopes tab.\nClick Add client scope.\nSelect the credential scope you created earlier (e.g., membership-credential).\nChoose Optional as the assignment type (recommended for credential scopes).\nThis ensures that the client can request and process the scope during the authorization flow, allowing the wallet to receive the corresponding Verifiable Credential.\nCreating a Client via the REST API\nAlternatively, you can create and configure the client programmatically. Ensure the oid4vci.enabled attribute is set to true and the required client scope is added to optionalClientScopes.\nCreate a JSON file (e.g., my-wallet-client.json) with the following content:\n{\n  \"clientId\": \"my-wallet-client\",\n  \"enabled\": true,\n  \"protocol\": \"openid-connect\",\n  \"publicClient\": false,\n  \"serviceAccountsEnabled\": true,\n  \"clientAuthenticatorType\": \"client-secret\",\n  \"redirectUris\": [\"http://localhost:8080/*\"],\n  \"directAccessGrantsEnabled\": true,\n  \"defaultClientScopes\": [\"profile\"],\n  \"optionalClientScopes\":"},
  {"id": "verifying-the-configuration", "title": "Verifying the Configuration", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#verifying-the-configuration", "md": "md/verifying-the-configuration.md", "text": "Validate the setup by accessing the issuer metadata endpoint:\nOpen a browser or use a tool like curl to visit:\nhttps://localhost:8443/.well-known/openid-credential-issuer/realms/oid4vc-vci\nA successful response returns a JSON object containing details such as: - Supported claims - Credential formats - Issuer metadata"},
  {"id": "conclusion", "title": "Conclusion", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#conclusion", "md": "md/conclusion.md", "text": "You have successfully configured Keycloak as a Verifiable Credential Issuer using the OID4VCI protocol. This setup leverages Keycloak’s robust identity management capabilities to issue secure, standards-compliant VCs.\nFor a complete reference implementation, see the sample project: OID4VCI deployment."},
  {"id": "_oid4vci_credential_offer_aia", "title": "Credential Offer via Application Initiated Action", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_credential_offer_aia", "md": "md/_oid4vci_credential_offer_aia.md", "text": "Keycloak provides a built-in Application Initiated Action (AIA) called verifiable_credential_offer that allows client applications to trigger credential issuance for a user during login. When this action is triggered, the user is presented with a page containing a QR code that can be scanned by a wallet application to claim the credential.\nBoth the Keycloak Account Console (Verifiable credentials tab → Issue to wallet) and the Admin Console (Users → Verifiable Credentials → Send credential offer) use this same AIA under the covers.\nThis section covers how to configure the action, how to trigger it from your application, and what the user experiences during the flow.\nEnabling and configuring the action\nThe verifiable_credential_offer action is automatically registered when the OID4VC_VCI feature is enabled. You can manage it in the Admin Console:\nNavigate to Authentication > Required actions.\nLocate the Register Verifiable Credential Offer action in the list.\nFigure 12. Required Actions configuration showing the Verifiable Credential Offer action\nFrom here you can:\nDisable the action — Toggle it off to prevent any application from triggering credential offers via AIA.\nConfigure re-authentication — Set the Max Age to control how long ago the user must have actively authenticated before being required to re-authenticate when the action is triggered. Set it to 0 to always require active re-authentication. If not configured, the default is five minutes. See Re-authentication during AIA for details.\nTriggering the action from your application\nTo trigger the credential offer AIA, your application redirects the user to the Keycloak authorization endpoint with the kc_action parameter. The parameter value consists of the action name followed by a colon and a Base64Url-encoded JSON configuration:\nkc_action=verifiable_credential_offer:<base64url-encoded-config>\nThe JSON configuration object has the following properties:\nProperty Required Description"},
  {"id": "_oid4vci_credential_request", "title": "Requesting Credentials", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_credential_request", "md": "md/_oid4vci_credential_request.md", "text": "This section explains how a wallet interacts with Keycloak to request and obtain a Verifiable Credential using the Authorization Code Flow.\n1. Discovering Issuer Metadata\nWallets often start from a credential offer, for example from a QR code or link. The credential offer contains the issuer identifier (credential_issuer), which the wallet uses to locate the Credential Issuer Metadata endpoint.\nThe wallet then discovers the issuer’s capabilities by calling the Credential Issuer Metadata endpoint. This endpoint provides details about the credential formats supported, cryptographic binding methods, and the URLs of other necessary endpoints (such as the authorization, token, and credential endpoints).\ncurl -s -X GET \"https://localhost:8443/.well-known/openid-credential-issuer/realms/{realm}\"\nThe JSON response contains the credential_configurations_supported object, which lists all available credentials and their configurations. From this metadata, the wallet determines the credential_configuration_id it wishes to request and identifies the credential_endpoint and token_endpoint.\n{\n  \"credential_issuer\": \"https://localhost:8443/realms/{realm}\",\n  \"credential_endpoint\": \"https://localhost:8443/realms/{realm}/protocol/oid4vc/credential\",\n  \"batch_credential_endpoint\": \"https://localhost:8443/realms/{realm}/protocol/oid4vc/batch-credential\",\n  \"nonce_endpoint\": \"https://localhost:8443/realms/{realm}/protocol/oid4vc/nonce\",\n  \"authorization_servers\": [\n    \"https://localhost:8443/realms/{realm}\"\n  ],\n  \"credential_configurations_supported\": {\n    \"membership-credential\": {\n      \"format\": \"jwt_vc_json\",\n      \"scope\": \"membership-credential\",\n      \"cryptographic_binding_methods_supported\": [\n        \"jwk\"\n      ],\n      \"credential_signing_alg_values_supported\": [\n        \"ES256\",\n        \"RS256\"\n      ],\n      \"credential_definition\": {\n        \"type\": [\n          \"VerifiableCredential\",\n          \"membership-credential\"\n        ]\n      },\n      \"proof_types_supported\":"},
  {"id": "_oid4vci_managing_credentials", "title": "Managing Issued Credentials", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_managing_credentials", "md": "md/_oid4vci_managing_credentials.md", "text": "Before issuing credentials, administrators must configure an OID4VCI client scope and assign a verifiable credential to the user (see Creating a User Account). Once issued via the OID4VCI protocol, credentials can be viewed, managed, and revoked by administrators through the Admin Console or Admin REST API, or by users through the Account Console. This section explains how to manage the credential lifecycle and handle compromise scenarios.\nViewing Credential Entitlements\nA credential entitlement represents a user’s authorization to receive a specific type of Verifiable Credential. Administrators assign these entitlements before credentials can be issued.\nTo view a user’s credential entitlements:\nIn the Admin Console, click Users in the menu.\nSelect the user.\nClick the Verifiable Credentials tab.\nFigure 16. Verifiable Credentials tab showing credential entitlements\nThe table lists each credential type assigned to the user. Use the kebab menu on each row to access available actions.\nFigure 17. Available actions for a credential entitlement\nThe following actions are available:\nView Attributes — Shows the user attribute snapshot associated with this credential type.\nView Issued Credentials — Opens a detail view of all credentials issued to the user for this type.\nUpdate Credential — Refreshes the stored user attributes and increments the credential revision.\nRevoke — Removes the credential entitlement and deletes all issued credential records for that user and credential type.\nSend Credential Offer — Sends a credential offer to the user via email (requires the user to have an email address configured).\nUnderstanding Attribute Snapshots and Credential Claims\nWhen an administrator creates a verifiable credential entitlement for a user, Keycloak stores a snapshot of the user’s attributes with the entitlement. The Update Credential action refreshes the stored snapshot and increments the credential revision.\nThe stored snapshot is not used"},
  {"id": "testing-with-third-party-wallets", "title": "Testing with third-party wallets", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#testing-with-third-party-wallets", "md": "md/testing-with-third-party-wallets.md", "text": "This section describes how to setup Keycloak for the integration with some third-party wallets.\nThis section describes a manual interoperability test with third-party wallets. It is not an automated compatibility test, and this integration is not officially supported. Third-party wallet behavior can change between wallet versions, and results should be verified again when upgrading either the wallet or Keycloak.\nTesting with Valera Wallet\nValera Wallet by A-SIT Plus is a demo wallet that can be used to test OpenID4VCI credential issuance. The test below was performed with a locally running Keycloak server exposed to the mobile wallet through an HTTPS tunnel. A production deployment is not required for this manual test, but the wallet must be able to reach the issuer through an HTTPS URL.\nTested Environment\nComponent Value\nWallet\nValera Wallet by A-SIT Plus\nWallet version\n5.8.0 on Android 12\nCredential configuration\nIdentityCredential\nCredential format\ndc+sd-jwt\nFlows tested\nAuthorization Code Flow and Pre-Authorized Code Flow\nResult\nBoth flows completed successfully and returned the issued credential to the wallet\nExposing Local Keycloak to the Wallet\nFor local testing, Keycloak can run on the development machine as described in the previous OID4VCI setup sections. Because the wallet runs on a phone and needs an HTTPS issuer URL, expose the local Keycloak endpoint through an HTTPS tunnel, for example with ngrok or a similar tool.\nIf Keycloak listens locally with HTTPS on port 8443, start the tunnel for that port:\nngrok http https://localhost:8443\nUse the public HTTPS tunnel hostname consistently for the credential offer and the issuer metadata seen by the wallet. The wallet must see credential offers, issuer metadata, authorization endpoints, token endpoints, and credential endpoints under the same public HTTPS hostname.\nThe HTTPS tunnel is used to make the local issuer reachable by the real mobile wallet. This setup is intended for manual interoperability testing."},
  {"id": "_oid4vci_proofs", "title": "Proof Types and Key Binding in OID4VCI", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_proofs", "md": "md/_oid4vci_proofs.md", "text": "A credential proof in OID4VCI is a cryptographic proof-of-possession that a wallet sends to an issuer (Keycloak) to show it controls the private key meant to be bound to the new credential.\nPurposes of the proof are:\nAnti-replay - the nonce in the proof prevents a captured credential request from being replayed\nKey binding - the public proof key embedded in the VC ties the credential to the Wallet’s key pair. When credential is later presented by the wallet to the credential verifier, verifier is able to cryptographically verify issuer as well as holder/wallet. Verifying of the holder is possible in case that key binding was used.\nExample use cases\nUse Case 1: Credential request without proof\nFigure 40. Credential request without proof\nWallet sends credential request without a proofs parameter\nIssuer/Keycloak issues the credential but has no key to bind (for instance, in case of SD-JWT credential format, there is no cnf claim)\nWallet creates the \"verifiable credential presentation\" and sends it to the verifier. However that presentation does not have key binding (for instance, in case of SD-JWT credential format, presentation ends with ~)\nVerifier is able to verify issuer signature and eventually disclosed claims digests. However verifier cannot verify holder key binding and hence cannot distinguish the presenter from anyone else who stole the credential. Risk is, that credential can be replayed or transferred to a different party.\nUse Case 2: Credential request with non-attested proof\nFigure 41. Credential request with proof\nWallet fetches c_nonce from Issuer’s nonce endpoint\nWallet generates a key pair before credential request (if it does not have existing key pair already). Wallet signs openid4vci-proof+jwt (in case that jwt proof was used, which is most typical for this use case). JWT header carries public proof key inline (typically in jwk claim). The proofs is sent within credential request to the issuer (Keycloak)\nIssuer validates proof JWT, extracts"},
  {"id": "_oid4vci_example_projects", "title": "Example projects", "breadcrumb": ["Configuring Keycloak as a Verifiable Credential Issuer"], "url": "index.html#_oid4vci_example_projects", "md": "md/_oid4vci_example_projects.md", "text": "For the illustration purpose, it is possible to use some example projects, which might be useful for quickstart OID4VCI setup and understand the concepts.\nOID4VCI deployment\nKeycloak playground\nThose are community projects used just for the illustration purposes and not for production environment. They are not officially supported by the Keycloak project team. Use them at your own discretion. Eventually, feel free to create github issues or pull requests in the corresponding github repositories if you find any issues related to those example projects."},
  {"id": "_vault-administration", "title": "Using a vault to obtain secrets", "breadcrumb": [], "url": "index.html#_vault-administration", "md": "md/_vault-administration.md", "text": "Keycloak currently provides two out-of-the-box implementations of the Vault SPI: a plain-text file-based vault and Java KeyStore-based vault.\nTo obtain a secret from a vault rather than entering it directly, enter the following specially crafted string into the appropriate field:\n${vault.key}\nwhere the key is the name of the secret recognized by the vault.\nTo prevent secrets from leaking across realms, Keycloak combines the realm name with the key obtained from the vault expression. This method means that the key does not directly map to an entry in the vault but creates the final entry name according to the algorithm used to combine the key with the realm name. In case of the file-based vault, such combination reflects to a specific filename, for the Java KeyStore-based vault it’s a specific alias name.\nYou can obtain the secret from the vault in the following fields:\nSMTP password\nIn the realm SMTP settings\nLDAP bind credential\nIn the LDAP settings of LDAP-based user federation.\nOIDC identity provider secret\nIn the Client Secret inside identity provider OpenID Connect Config\nOIDC client secret\nIn the Client Secret inside confidential OpenID Connect Client."},
  {"id": "_vault-key-resolvers", "title": "Key resolvers", "breadcrumb": ["Using a vault to obtain secrets"], "url": "index.html#_vault-key-resolvers", "md": "md/_vault-key-resolvers.md", "text": "All built-in providers support the configuration of key resolvers. A key resolver implements the algorithm or strategy for combining the realm name with the key, obtained from the ${vault.key} expression, into the final entry name used to retrieve the secret from the vault. Keycloak uses the keyResolvers property to configure the resolvers that the provider uses. The value is a comma-separated list of resolver names. An example of the configuration for the files-plaintext provider follows:\nkc.[sh|bat] start --spi-vault--file--key-resolvers=REALM_UNDERSCORE_KEY,KEY_ONLY\nThe resolvers run in the same order you declare them in the configuration. For each resolver, Keycloak uses the last entry name the resolver produces, which combines the realm with the vault key to search for the vault’s secret. If Keycloak finds a secret, it returns the secret. If not, Keycloak uses the next resolver. This search continues until Keycloak finds a non-empty secret or runs out of resolvers. If Keycloak finds no secret, Keycloak returns an empty secret.\nIn the previous example, Keycloak uses the REALM_UNDERSCORE_KEY resolver first. If Keycloak finds an entry in the vault that using that resolver, Keycloak returns that entry. If not, Keycloak searches again using the KEY_ONLY resolver. If Keycloak finds an entry by using the KEY_ONLY resolver, Keycloak returns that entry. If Keycloak uses all resolvers, Keycloak returns an empty secret.\nA list of the currently available resolvers follows:\nName Description\nKEY_ONLY\nKeycloak ignores the realm name and uses the key from the vault expression. Keycloak escapes occurrences of underscores in the key with another underscore character. For example, if the key is called my_secret, Keycloak searches for an entry in the vault named my__secret. This is to prevent conflicts with the default REALM_UNDERSCORE_KEY resolver.\nREALM_UNDERSCORE_KEY\nKeycloak combines the realm and key by using an underscore character. Keycloak escapes occurrences of"},
  {"id": "configuring-auditing-to-track-events", "title": "Configuring auditing to track events", "breadcrumb": [], "url": "index.html#configuring-auditing-to-track-events", "md": "md/configuring-auditing-to-track-events.md", "text": "Keycloak includes a suite of auditing capabilities. You can record every login and administrator action and review those actions in the Admin Console. Keycloak also includes a Listener SPI that listens for events and can trigger actions. Examples of built-in listeners include log files and sending emails if an event occurs."},
  {"id": "auditing-user-events", "title": "Auditing user events", "breadcrumb": ["Configuring auditing to track events"], "url": "index.html#auditing-user-events", "md": "md/auditing-user-events.md", "text": "You can record and view every event that affects users. Keycloak triggers login events for actions such as successful user login, a user entering an incorrect password, or a user account updating. By default, Keycloak does not store or display events in the Admin Console. Only the error events are logged to the Admin Console and the server’s log file.\nProcedure\nUse this procedure to start auditing user events.\nClick Realm settings in the menu.\nClick the Events tab.\nClick the User events settings tab.\nToggle Save events to ON.\nUser events settings\nSpecify the length of time to store events in the Expiration field.\nClick Add saved types to see other events you can save.\nAdd types\nClick Add.\nClick Clear user events when you want to delete all saved events.\nProcedure\nYou can now view events.\nClick the Events tab in the menu.\nUser events\nTo filter events, click Search user event.\nSearch user event\nEvent types\nLogin events:\nEvent Description\nLogin\nA user logs in.\nRegister\nA user registers.\nLogout\nA user logs out.\nCode to Token\nAn application, or client, exchanges a code for a token.\nRefresh Token\nAn application, or client, refreshes a token.\nBrute force protection:\nEvent Description\nUser disabled by permanent lockout\nBrute force protection disabled the user account permanently due to too many login failures.\nUser disabled by temporary lockout\nBrute force protection disabled the user account temporarily due to too many login failures.\nIdentity Brokering:\nEvent Description\nFederated identity link override\nAn existing Federated identity link was overridden\nFederated identity link override error\nError occurred when trying to override an existing Federated identity link\nOAuth:\nEvent Description\nOAuth2 extension grant\nOAuth2 grant was executed\nOAuth2 extension grant error\nError occurred during OAuth2 grant execution\nAccount events:\nEvent Description\nSocial Link\nA user account links to a social media provider.\nRemove Social Link\nThe link from a social media account to a user"},
  {"id": "auditing-admin-events", "title": "Auditing admin events", "breadcrumb": ["Configuring auditing to track events"], "url": "index.html#auditing-admin-events", "md": "md/auditing-admin-events.md", "text": "You can record all actions that are performed by an administrator in the Admin Console. The Admin Console performs administrative actions by invoking the Keycloak REST interface and Keycloak audits these REST invocations. You can view the resulting events in the Admin Console.\nProcedure\nUse this procedure to start auditing admin actions.\nClick Realm settings in the menu.\nClick the Events tab.\nClick the Admin events settings tab.\nToggle Save events to ON.\nKeycloak displays the Include representation switch.\nToggle Include representation to ON.\nThe Include Representation switch includes JSON documents sent through the admin REST API so you can view the administrators actions.\nAdmin events settings\nClick Save.\nTo clear the database of stored actions, click Clear admin events.\nProcedure\nYou can now view admin events.\nClick Events in the menu.\nClick the Admin events tab.\nAdmin events\nWhen the Include Representation switch is ON, it can lead to storing a lot of information in the database. You can set a maximum length of the representation by using the --spi-events-store--jpa--max-field-length argument. This setting is useful if you want to adhere to the underlying storage limitation. For example:\nkc.[sh|bat] --spi-events-store--jpa--max-field-length=2500"},
  {"id": "mitigating_security_threats", "title": "Mitigating security threats", "breadcrumb": [], "url": "index.html#mitigating_security_threats", "md": "md/mitigating_security_threats.md", "text": "Security vulnerabilities exist in any authentication server. See the Internet Engineering Task Force’s (IETF) OAuth 2.0 Threat Model and the OAuth 2.0 Security Best Current Practice for more information."},
  {"id": "host", "title": "Host", "breadcrumb": ["Mitigating security threats"], "url": "index.html#host", "md": "md/host.md", "text": "Keycloak uses the public hostname in several ways, such as within token issuer fields and URLs in password reset emails.\nBy default, the hostname derives from request headers. No validation exists to ensure a hostname is valid. If you are not using a load balancer, or proxy, with Keycloak to prevent invalid host headers, configure the acceptable hostnames.\nThe hostname’s Service Provider Interface (SPI) provides a way to configure the hostname for requests. You can use this built-in provider to set a fixed URL for frontend requests while allowing backend requests based on the request URI. If the built-in provider does not have the required capability, you can develop a customized provider."},
  {"id": "admin-endpoints-and-admin-console", "title": "Admin endpoints and Admin Console", "breadcrumb": ["Mitigating security threats"], "url": "index.html#admin-endpoints-and-admin-console", "md": "md/admin-endpoints-and-admin-console.md", "text": "Keycloak exposes the administrative REST API and the web console on the same port as non-administrative usage. Do not expose administrative endpoints externally if external access is not necessary."},
  {"id": "password-guess-brute-force-attacks", "title": "Brute force attacks", "breadcrumb": ["Mitigating security threats"], "url": "index.html#password-guess-brute-force-attacks", "md": "md/password-guess-brute-force-attacks.md", "text": "A brute force attack attempts to guess a user’s password by trying to log in multiple times. Keycloak has brute force detection capabilities and can permanently or temporarily disable a user account if the number of login failures exceeds a specified threshold.\nThe protection is applied only to authentication mechanisms prone to the brute force attacks. Keycloak applies it only to password, OTP and recovery codes.\nWhen a user is locked and attempts to log in, Keycloak displays the default Invalid username or password error message. This message is the same error message as the message displayed for an invalid username or invalid password to ensure the attacker is unaware the account is disabled.\nBrute force detection is disabled by default. Enable this feature to protect against brute force attacks.\nTo enable this protection:\nClick Realm Settings in the menu\nClick the Security Defenses tab.\nClick the Brute Force Detection tab.\nChoose the Brute Force Mode which best fit to your requirements.\nBrute force detection\nLockout permanently\nKeycloak disables a user account (blocking log in attempts) until an administrator re-enables it.\nLockout permanently\nPermanent Lockout Parameters\nName Description Default\nMax Login Failures\nThe maximum number of login failures.\n30 failures\nQuick Login Check Milliseconds\nThe minimum time between login attempts.\n1000 milliseconds\nMinimum Quick Login Wait\nThe minimum time the user is disabled when login attempts are quicker than Quick Login Check Milliseconds.\n1 minute\nPermanent Lockout Algorithm\nOn successful login\nReset count\ncall secondary authentication check (success)\nOn failed login\nIncrement count\nIf count is greater than or equals to Max login failures\nlocks the user\nElse if the time between this failure and the last failure is less than Quick Login Check Milliseconds\nLocks the user for the time specified at Minimum Quick Login Wait\ncall secondary authentication check (fail)\nEnabling an user account resets the count.\nLockout"},
  {"id": "password-policies", "title": "Password policies", "breadcrumb": ["Mitigating security threats"], "url": "index.html#password-policies", "md": "md/password-policies.md", "text": "Ensure you have a complex password policy to force users to choose complex passwords. See the Password Policies chapter for more information. Prevent password guessing by setting up the Keycloak server to use one-time-passwords."},
  {"id": "read_only_user_attributes", "title": "Read-only user attributes", "breadcrumb": ["Mitigating security threats"], "url": "index.html#read_only_user_attributes", "md": "md/read_only_user_attributes.md", "text": "Typical users who are stored in Keycloak have various attributes related to their user profiles. Such attributes include email, firstName or lastName. However users may also have attributes, which are not typical profile data, but rather metadata. The metadata attributes usually should be read-only for the users and the typical users never should have a way to update those attributes from the Keycloak user interface or Account REST API. Some of the attributes should be even read-only for the administrators when creating or updating user with the Admin REST API.\nThe metadata attributes are usually attributes from those groups:\nVarious links or metadata related to the user storage providers. For example in case of the LDAP integration, the LDAP_ID attribute contains the ID of the user in the LDAP server.\nMetadata provisioned by User Storage. For example createdTimestamp provisioned from the LDAP should be always read-only by user or administrator.\nMetadata related to various authenticators. For example KERBEROS_PRINCIPAL attribute can contain the kerberos principal name of the particular user. Similarly attribute usercertificate can contain metadata related to binding the user with the data from the X.509 certificate, which is used typically when X.509 certificate authentication is enabled.\nMetadata related to the identificator of users by the applications/clients. For example saml.persistent.name.id.for.my_app can contain SAML NameID, which will be used by the client application my_app as the identifier of the user.\nMetadata related to the authorization policies, which are used for the attribute based access control (ABAC). Values of those attributes may be used for the authorization decisions. Hence it is important that those attributes cannot be updated by the users.\nFrom the long term perspective, Keycloak will have a proper User Profile SPI, which will allow fine-grained configuration of every user attribute. Currently this capability is not fully available yet."},
  {"id": "validate_user_attributes", "title": "Validate user attributes", "breadcrumb": ["Mitigating security threats"], "url": "index.html#validate_user_attributes", "md": "md/validate_user_attributes.md", "text": "With the functionality in Managing user attributes, administrators can restrict the data users enter for attributes, for example, in user registration or the account console.\nAdministrators should not allow unmanaged attributes for users to prevent attackers adding an unlimited number of attributes. Attributes should have a validation that restricts the amount of data entered by attackers.\nWhen using regular expressions to validate user attributes, avoid regular expressions that use an excessive amount of memory or CPU. See OWASP’s Regular expression Denial of Service for details."},
  {"id": "clickjacking", "title": "Clickjacking", "breadcrumb": ["Mitigating security threats"], "url": "index.html#clickjacking", "md": "md/clickjacking.md", "text": "Clickjacking is a technique of tricking users into clicking on a user interface element different from what users perceive. A malicious site loads the target site in a transparent iFrame, overlaid on top of a set of dummy buttons placed directly under important buttons on the target site. When a user clicks a visible button, they are clicking a button on the hidden page. An attacker can steal a user’s authentication credentials and access their resources by using this method.\nBy default, every response by Keycloak sets some specific HTTP headers that can prevent this from happening. Specifically, it sets X-Frame-Options and Content-Security-Policy. You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control.\nProcedure\nIn the Admin Console, you can specify the values of the X-Frame-Options and Content-Security-Policy headers.\nClick the Realm Settings menu item.\nClick the Security Defenses tab.\nSecurity Defenses\nBy default, Keycloak only sets up a same-origin policy for iframes."},
  {"id": "sslhttps-requirement", "title": "SSL/HTTPS requirement", "breadcrumb": ["Mitigating security threats"], "url": "index.html#sslhttps-requirement", "md": "md/sslhttps-requirement.md", "text": "OAuth 2.0/OpenID Connect uses access tokens for security. Attackers can scan your network for access tokens and use them to perform malicious operations for which the token has permission. This attack is known as a man-in-the-middle attack. Use SSL/HTTPS for communication between the Keycloak auth server and the clients Keycloak secures to prevent man-in-the-middle attacks.\nKeycloak has three modes for SSL/HTTPS. SSL is complex to set up, so Keycloak allows non-HTTPS communication over private IP addresses such as localhost, 192.168.x.x, and other private IP addresses. In production, ensure you enable SSL and SSL is compulsory for all operations.\nOn the adapter/client-side, you can disable the SSL trust manager. The trust manager ensures the client’s identity that Keycloak communicates with is valid and ensures the DNS domain name against the server’s certificate. In production, ensure that each of your client adapters uses a truststore to prevent DNS man-in-the-middle attacks."},
  {"id": "csrf-attacks", "title": "CSRF attacks", "breadcrumb": ["Mitigating security threats"], "url": "index.html#csrf-attacks", "md": "md/csrf-attacks.md", "text": "A Cross-site request forgery (CSRF) attack uses HTTP requests from users that websites have already authenticated. Any site using cookie-based authentication is vulnerable to CSRF attacks. You can mitigate these attacks by matching a state cookie against a posted form or query parameter.\nThe OAuth 2.0 login specification requires that a state cookie matches against a transmitted state parameter. Keycloak fully implements this part of the specification, so all logins are protected.\nThe Keycloak Admin Console is a JavaScript/HTML5 application that makes REST calls to the backend Keycloak admin REST API. These calls all require bearer token authentication and consist of JavaScript Ajax calls, so CSRF is impossible. You can configure the admin REST API to validate the CORS origins.\nThe Account Console in Keycloak can be vulnerable to CSRF. To prevent CSRF attacks, Keycloak sets a state cookie and embeds the value of this cookie in hidden form fields or query parameters within action links. Keycloak checks the query/form parameter against the state cookie to verify that the same user made the call."},
  {"id": "unspecific-redirect-uris_server_administration_guide", "title": "Unspecific redirect URIs", "breadcrumb": ["Mitigating security threats"], "url": "index.html#unspecific-redirect-uris_server_administration_guide", "md": "md/unspecific-redirect-uris_server_administration_guide.md", "text": "Make your registered redirect URIs as specific as feasible. Registering vague redirect URIs for Authorization Code Flows can allow malicious clients to impersonate another client with broader access. Impersonation can happen if two clients live under the same domain, for example.\nYou can use secure redirect uris enforcer executor for your realm. The result makes sure that client administrators are able to register only clients with specific redirect-uris matching various requirements such as requiring that a URL cannot have wildcards in the context path or can be limited to specified permitted domains. See Client Policies for details about how to configure client policies with a specific executor."},
  {"id": "fapi-compliance", "title": "FAPI compliance", "breadcrumb": ["Mitigating security threats"], "url": "index.html#fapi-compliance", "md": "md/fapi-compliance.md", "text": "To make sure that Keycloak server will validate your client to be more secure and FAPI compliant, you can configure client policies for the FAPI support. FAPI details are described in the securing apps section. Among other things, this ensures some security best practices described above like SSL required for clients, secure redirect URI used and more of similar best practices."},
  {"id": "oauth-2-1-compliance", "title": "OAuth 2.1 compliance", "breadcrumb": ["Mitigating security threats"], "url": "index.html#oauth-2-1-compliance", "md": "md/oauth-2-1-compliance.md", "text": "To make sure that Keycloak server will validate your client to be more secure and OAuth 2.1 compliant, you can configure client policies for the OAuth 2.1 support. OAuth 2.1 details are described in the securing apps section."},
  {"id": "compromised-access-and-refresh-tokens", "title": "Compromised access and refresh tokens", "breadcrumb": ["Mitigating security threats"], "url": "index.html#compromised-access-and-refresh-tokens", "md": "md/compromised-access-and-refresh-tokens.md", "text": "Keycloak includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between Keycloak and its clients and applications. Keycloak does not enable SSL by default.\nAnother action to mitigate damage from leaked access tokens is to shorten the token’s lifespans. You can specify token lifespans within the timeouts page. Short lifespans for access tokens force clients and applications to refresh their access tokens after a short time. If an admin detects a leak, the admin can log out all user sessions to invalidate these refresh tokens or set up a revocation policy.\nEnsure refresh tokens always stay private to the client and are never transmitted.\nYou can mitigate damage from leaked access tokens and refresh tokens by issuing these tokens as holder-of-key tokens. See OAuth 2.0 Mutual TLS Client Certificate Bound Access Token for more information.\nIf an access token or refresh token is compromised, access the Admin Console and push a not-before revocation policy to all applications. Pushing a not-before policy ensures that any tokens issued before that time become invalid. Pushing a new not-before policy ensures that applications must download new public keys from Keycloak and mitigate damage from a compromised realm signing key. See the keys chapter for more information.\nYou can disable specific applications, clients, or users if they are compromised."},
  {"id": "compromised-authorization-code", "title": "Compromised authorization code", "breadcrumb": ["Mitigating security threats"], "url": "index.html#compromised-authorization-code", "md": "md/compromised-authorization-code.md", "text": "For the OIDC Auth Code Flow, Keycloak generates a cryptographically strong random value for its authorization codes. An authorization code is used only once to obtain an access token.\nOn the timeouts page in the Admin Console, you can specify the length of time an authorization code is valid. Ensure that the length of time is less than 10 seconds, which is long enough for a client to request a token from the code.\nYou can also defend against leaked authorization codes by applying Proof Key for Code Exchange (PKCE) to clients."},
  {"id": "open-redirectors", "title": "Open redirectors", "breadcrumb": ["Mitigating security threats"], "url": "index.html#open-redirectors", "md": "md/open-redirectors.md", "text": "An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without validation. An attacker can use the end-user authorization endpoint and the redirect URI parameter to use the authorization server as an open redirector, using a user’s trust in an authorization server to launch a phishing attack.\nKeycloak requires that all registered applications and clients register at least one redirection URI pattern. When a client requests that Keycloak performs a redirect, Keycloak checks the redirect URI against the list of valid registered URI patterns. Clients and applications must register as specific a URI pattern as possible to mitigate open redirector attacks.\nIf an application requires a non http(s) custom scheme, it should be an explicit part of the validation pattern (for example custom:/app/*). For security reasons a general pattern like * does not cover non http(s) schemes.\nBy using Client Policies, an administrator can make sure that clients cannot register open redirect URLs such as *."},
  {"id": "ssrf", "title": "Mitigating Server-Side Request Forgery (SSRF)", "breadcrumb": ["Mitigating security threats"], "url": "index.html#ssrf", "md": "md/ssrf.md", "text": "Server-Side Request Forgery (SSRF) is a security vulnerability where an attacker induces the server (Keycloak, in this case) to make requests to an unintended destination. In Keycloak, this risk is primarily associated with client fields that trigger requests from the server, such as the JWKS URI.\nIf these fields are not strictly validated, a malicious administrator, a compromised account or a Dynamic Client Registration could point them toward internal network resources or loopback interfaces (e.g., http://localhost:8080/any), allowing the attacker to probe or attack the internal infrastructure from the Keycloak server itself.\nTo mitigate this threat, Keycloak provides a solution using Client Policies with some executors like Secure Client Uris to provide baseline protection for transport security and wildcards, but especially with the Secure Client URIs Pattern executor.\nSee also DNS Rebinding for an attack vector that can bypass URI-based validation.\nSecure Client URIs Pattern Executor\nThis executor enforces a strict security policy by validating client URIs against an allowlist of patterns. If a URI does not match at least one of the configured patterns, the client creation or update is rejected.\nIt can be used not only for JWKS URI but to validate all available uri fields of the client like including rootUrl, adminUrl, redirectUris, webOrigins and others.\nTable 13. Configuration Properties\nConfiguration Description\nAllowed URI Patterns\nA list of Regular Expressions. A client URI is considered valid only if it matches at least one of these patterns. If this list is empty or invalid, the executor blocks all URIs.\nClient URI Fields to validate\nA list of specific client fields to validate (e.g., jwksUri, adminUrl). If left empty, all supported URI fields are validated by default. The list is available in the configuration.\nAnti-SSRF Pattern Examples\nTo effectively prevent SSRF, Regular Expressions should be designed to exclude IP addresses and local hostnames.\n1."},
  {"id": "password-database-compromised", "title": "Password database compromised", "breadcrumb": ["Mitigating security threats"], "url": "index.html#password-database-compromised", "md": "md/password-database-compromised.md", "text": "Keycloak does not store passwords in raw text but as hashed text, using the PBKDF2-HMAC-SHA512 message digest algorithm. Keycloak performs 210,000 hashing iterations, the number of iterations recommended by the security community. This number of hashing iterations can adversely affect performance as PBKDF2 hashing uses a significant amount of CPU resources."},
  {"id": "limiting-scope", "title": "Limiting scope", "breadcrumb": ["Mitigating security threats"], "url": "index.html#limiting-scope", "md": "md/limiting-scope.md", "text": "Scope availability\nBy default, new client applications have unlimited role scope mappings. Every access token for that client contains all permissions that the user has. If an attacker compromises the client and obtains the client’s access tokens, each system that the user can access is compromised.\nLimit the roles of an access token by using the Scope menu for each client. Alternatively, you can set role scope mappings at the Client Scope level and assign Client Scopes to your client by using the Client Scope menu.\nRemoving the offline scope for a client also removes the ability to issue long-lived offline tokens for a client and offers better control over sessions by users.\nScope visibility\nBy default, all scopes are included in the OpenID Connect discovery endpoint. To reduce the discoverability and OSINT-exposure, you can configure each scope to be excluded by disabling Include in OpenID Provider Metadata."},
  {"id": "limit-token-audience", "title": "Limit token audience", "breadcrumb": ["Mitigating security threats"], "url": "index.html#limit-token-audience", "md": "md/limit-token-audience.md", "text": "In environments with low levels of trust among services, limit the audiences on the token. See the OAuth2 Threat Model and the Audience Support section for more information."},
  {"id": "_limit-authentication-sessions", "title": "Limit Authentication Sessions", "breadcrumb": ["Mitigating security threats"], "url": "index.html#_limit-authentication-sessions", "md": "md/_limit-authentication-sessions.md", "text": "Authentication sessions track the state of the authentication. The text below is applicable regardless of the source flow.\nThis section describes deployments that use the Infinispan provider for authentication sessions.\nAuthentication session is internally stored as RootAuthenticationSessionEntity. Each RootAuthenticationSessionEntity can have multiple authentication sub-sessions stored within the RootAuthenticationSessionEntity as a collection of AuthenticationSessionEntity objects. Keycloak stores authentication sessions in a dedicated Infinispan cache. The number of AuthenticationSessionEntity per RootAuthenticationSessionEntity contributes to the size of each cache entry. Total memory footprint of authentication session cache is determined by the number of stored RootAuthenticationSessionEntity and by the number of AuthenticationSessionEntity within each RootAuthenticationSessionEntity.\nThe number of maintained RootAuthenticationSessionEntity objects corresponds to the number of unfinished login flows from the browser. To keep the number of RootAuthenticationSessionEntity under control, using an advanced firewall control to limit ingress network traffic is recommended.\nHigher memory usage may occur for deployments where there are many active RootAuthenticationSessionEntity with a lot of AuthenticationSessionEntity. If the load balancer does not support or is not configured for session stickiness, the load over network in a cluster can increase significantly. The reason for this load is that each request that lands on a node that does not own the appropriate authentication session needs to retrieve and update the authentication session record in the owner node which involves a separate network transmission for both the retrieval and the storage.\nThe maximum number of AuthenticationSessionEntity per RootAuthenticationSessionEntity can be configured in authenticationSessions SPI by setting property authSessionsLimit. The default value is set to 300"},
  {"id": "sql-injection-attacks", "title": "SQL injection attacks", "breadcrumb": ["Mitigating security threats"], "url": "index.html#sql-injection-attacks", "md": "md/sql-injection-attacks.md", "text": "Currently, Keycloak has no known SQL injection vulnerabilities."},
  {"id": "_account-service", "title": "Account Console", "breadcrumb": [], "url": "index.html#_account-service", "md": "md/_account-service.md", "text": "Keycloak users can manage their accounts through the Account Console. They can configure their profiles, add two-factor authentication, include identity provider accounts, and oversee device activity.\nAdditional resources\nThe Account Console can be configured in terms of appearance and language preferences. An example is adding additional attributes to the Personal info page. For more information, see the Server Developer Guide."},
  {"id": "accessing-the-account-console", "title": "Accessing the Account Console", "breadcrumb": ["Account Console"], "url": "index.html#accessing-the-account-console", "md": "md/accessing-the-account-console.md", "text": "Procedure\nMake note of the realm name and IP address for the Keycloak server where your account exists.\nIn a web browser, enter a URL in this format: server-root/realms/{realm-name}/account.\nEnter your login name and password.\nAccount Console\nYou can also ask for additional scopes when calling the account console URL by setting the scope parameter in this format: server-root/realms/{realm-name}/account?scope=phone."},
  {"id": "configuring-ways-to-sign-in", "title": "Configuring ways to sign in", "breadcrumb": ["Account Console"], "url": "index.html#configuring-ways-to-sign-in", "md": "md/configuring-ways-to-sign-in.md", "text": "You can sign in to this console using basic authentication (a login name and password) or two-factor authentication. For two-factor authentication, use one of the following procedures.\nTwo-factor authentication with OTP\nPrerequisites\nOTP is a valid authentication mechanism for your realm.\nProcedure\nClick Account security in the menu.\nClick Signing in.\nClick Set up Authenticator application.\nSigning in\nFollow the directions that appear on the screen to use your mobile device as your OTP generator.\nScan the QR code in the screen shot into the OTP generator on your mobile device.\nLog out and log in again.\nRespond to the prompt by entering an OTP that is provided on your mobile device.\nTwo-factor authentication with WebAuthn\nPrerequisites\nWebAuthn is a valid two-factor authentication mechanism for your realm. Please follow the WebAuthn section for more details.\nProcedure\nClick Account Security in the menu.\nClick Signing In.\nClick Set up a Passkey.\nSigning In\nPrepare your Passkey. How you prepare this key depends on the type of Passkey you use. For example, for a USB based Yubikey, you may need to put your key into the USB port on your laptop.\nClick Register to register your Passkey.\nLog out and log in again.\nAssuming authentication flow was correctly set, a message appears asking you to authenticate with your Passkey as second factor.\nPasswordless authentication with WebAuthn\nPrerequisites\nWebAuthn is a valid passwordless authentication mechanism for your realm. Please follow the Passwordless WebAuthn section for more details.\nProcedure\nClick Account Security in the menu.\nClick Signing In.\nClick Set up a Passkey in the Passwordless section.\nSigning In\nPrepare your Passkey. How you prepare this key depends on the type of Passkey you use. For example, for a USB based Yubikey, you may need to put your key into the USB port on your laptop.\nClick Register to register your Passkey.\nLog out and log in again.\nAssuming authentication flow was correctly set, a message appears"},
  {"id": "viewing-device-activity", "title": "Viewing device activity", "breadcrumb": ["Account Console"], "url": "index.html#viewing-device-activity", "md": "md/viewing-device-activity.md", "text": "You can view the devices that are logged in to your account.\nProcedure\nClick Account security in the menu.\nClick Device activity.\nLog out a device if it looks suspicious.\nDevices"},
  {"id": "adding-an-identity-provider-account", "title": "Adding an identity provider account", "breadcrumb": ["Account Console"], "url": "index.html#adding-an-identity-provider-account", "md": "md/adding-an-identity-provider-account.md", "text": "You can link your account with an identity broker. This option is often used to link social provider accounts.\nProcedure\nLog into the Admin Console.\nClick Identity providers in the menu.\nSelect a provider and complete the fields.\nReturn to the Account Console.\nClick Account security in the menu.\nClick Linked accounts.\nThe identity provider you added appears in this page.\nLinked Accounts"},
  {"id": "accessing-other-applications", "title": "Accessing other applications", "breadcrumb": ["Account Console"], "url": "index.html#accessing-other-applications", "md": "md/accessing-other-applications.md", "text": "The Applications menu item shows users which applications you can access. In this case, only the Account Console is available.\nApplications\nEnding an application session\nYou can end your active sessions with a specific application directly from the Applications page. Applications that have an active session are marked as In use and display an End application session button. The Account Console itself does not display this button.\nProcedure\nClick Applications in the menu.\nFind the application whose session you want to end.\nClick End application session next to the application.\nClick Confirm in the confirmation dialog.\nYour sessions with the application are ended, including any offline sessions. If the application supports it, Keycloak also notifies the application. Because this does not sign you out from Keycloak, the application can sign you in again without asking for your credentials when you access it again. To fully sign out from all applications, use the Sign out action on the Device activity page instead.\nEnding an application session does not revoke the access you granted to the application, so it can obtain new sessions the next time you use it. To revoke the granted access, use the Remove access action for the application."},
  {"id": "viewing-group-memberships", "title": "Viewing group memberships", "breadcrumb": ["Account Console"], "url": "index.html#viewing-group-memberships", "md": "md/viewing-group-memberships.md", "text": "You can view the groups you are associated with by clicking the Groups menu. If you select Direct membership checkbox, you will see only the groups you are direct associated with.\nPrerequisites\nYou need to have the view-groups account role for being able to view Groups menu.\nView group memberships"},
  {"id": "admin-cli", "title": "Admin CLI", "breadcrumb": [], "url": "index.html#admin-cli", "md": "md/admin-cli.md", "text": "With Keycloak, you can perform administration tasks from the command-line interface (CLI) by using the Admin CLI command-line tool."},
  {"id": "installing-the-admin-cli", "title": "Installing the Admin CLI", "breadcrumb": ["Admin CLI"], "url": "index.html#installing-the-admin-cli", "md": "md/installing-the-admin-cli.md", "text": "Keycloak packages the Admin CLI server distribution with the execution scripts in the bin directory.\nThe Linux script is called kcadm.sh, and the script for Windows is called kcadm.bat. Add the Keycloak server directory to your PATH to use the client from any location on your file system.\nFor example:\nLinux:\n$ export PATH=$PATH:$KEYCLOAK_HOME/bin\n$ kcadm.sh\nWindows:\nc:\\> set PATH=%PATH%;%KEYCLOAK_HOME%\\bin\nc:\\> kcadm\nYou must set the KEYCLOAK_HOME environment variable to the path where you extracted the Keycloak Server distribution.\nTo avoid repetition, the rest of this document only uses Windows examples in places where the CLI differences are more than just in the kcadm command name."},
  {"id": "using-the-admin-cli", "title": "Using the Admin CLI", "breadcrumb": ["Admin CLI"], "url": "index.html#using-the-admin-cli", "md": "md/using-the-admin-cli.md", "text": "The Admin CLI makes HTTP requests to Admin REST endpoints. Access to the Admin REST endpoints requires authentication.\nConsult the Admin REST API documentation for details about JSON attributes for specific endpoints.\nStart an authenticated session by logging in. You can now perform create, read, update, and delete (CRUD) operations.\nFor example:\nLinux:\n$ kcadm.sh config credentials --server http://localhost:8080 --realm demo --user admin --client admin\n$ kcadm.sh create realms -s realm=demorealm -s enabled=true -o\n$ CID=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=[\"http://localhost:8980/myapp/*\"]' -i)\n$ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json\nWindows:\nc:\\> kcadm config credentials --server http://localhost:8080 --realm demo --user admin --client admin\nc:\\> kcadm create realms -s realm=demorealm -s enabled=true -o\nc:\\> kcadm create clients -r demorealm -s clientId=my_client -s \"redirectUris=[\\\"http://localhost:8980/myapp/*\\\"]\" -i > clientid.txt\nc:\\> set /p CID=<clientid.txt\nc:\\> kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json\nIn a production environment, access Keycloak by using https: to avoid exposing tokens. If a trusted certificate authority, included in Java’s default certificate truststore, has not issued a server’s certificate, prepare a truststore.jks file and instruct the Admin CLI to use it.\nFor example:\nLinux:\n$ kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks\nWindows:\nc:\\> kcadm config truststore --trustpass %PASSWORD% %HOMEPATH%\\.keycloak\\truststore.jks"},
  {"id": "sensitive-options", "title": "Sensitive Options", "breadcrumb": ["Admin CLI"], "url": "index.html#sensitive-options", "md": "md/sensitive-options.md", "text": "Sensitive values, such as passwords, may be specified as command options. That is generally not recommended. There are also mechanisms by which you can be prompted for the sensitive value by either omitting the option or providing a value. Finally all will have a corresponding env variable that can be used instead. Check the help of the command you are running to see all possible options."},
  {"id": "authenticating", "title": "Authenticating", "breadcrumb": ["Admin CLI"], "url": "index.html#authenticating", "md": "md/authenticating.md", "text": "When you log in with the Admin CLI, you specify:\nA server endpoint URL\nA realm\nA user name\nAnother option is to specify a clientId only, which creates a unique service account for you to use.\nWhen you log in using a user name, use a password for the specified user. When you log in using a clientId, you need the client secret only, not the user password. You can also use the Signed JWT rather than the client secret.\nEnsure the account used for the session has the proper permissions to invoke Admin REST API operations. For example, the realm-admin role of the realm-management client can administer the realm of the user.\nTwo primary mechanisms are available for authentication. One mechanism uses kcadm config credentials to start an authenticated session.\n$ kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin\nThis mechanism maintains an authenticated session between the kcadm command invocations by saving the obtained access token and its associated refresh token. It can maintain other secrets in a private configuration file. See the next chapter for more information.\nThe second mechanism authenticates each command invocation for the duration of the invocation. This mechanism increases the load on the server and the time spent on round trips obtaining tokens. The benefit of this approach is that it is unnecessary to save tokens between invocations, so nothing is saved to disk. Keycloak uses this mode when the --no-config argument is specified.\nFor example, when performing an operation, specify all the information required for authentication.\n$ kcadm.sh get realms --no-config --server http://localhost:8080 --realm master --user admin\nRun the kcadm.sh help command for more information on using the Admin CLI.\nRun the kcadm.sh config credentials --help command for more information about starting an authenticated session.\nIf you do not specify the --password option (it is generally recommended to not provide passwords as part of the"},
  {"id": "_working_with_alternative_configurations", "title": "Working with alternative configurations", "breadcrumb": ["Admin CLI"], "url": "index.html#_working_with_alternative_configurations", "md": "md/_working_with_alternative_configurations.md", "text": "By default, the Admin CLI maintains a configuration file named kcadm.config. Keycloak places this file in the user’s home directory. In Linux-based systems, the full pathname is $HOME/.keycloak/kcadm.config. In Windows, the full pathname is %HOMEPATH%\\.keycloak\\kcadm.config.\nYou can use the --config option to point to a different file or location so you can maintain multiple authenticated sessions in parallel.\nPerform operations tied to a single configuration file from a single thread.\nEnsure the configuration file is invisible to other users on the system. It contains access tokens and secrets that must be private. Keycloak creates the ~/.keycloak directory and its contents automatically with proper access limits. If the directory already exists, Keycloak does not update the directory’s permissions.\nIt is possible to avoid storing secrets inside a configuration file, but doing so is inconvenient and increases the number of token requests. Use the --no-config option with all commands and specify the authentication information the config credentials command requires with each invocation of kcadm."},
  {"id": "basic-operations-and-resource-uris", "title": "Basic operations and resource URIs", "breadcrumb": ["Admin CLI"], "url": "index.html#basic-operations-and-resource-uris", "md": "md/basic-operations-and-resource-uris.md", "text": "The Admin CLI can generically perform CRUD operations against Admin REST API endpoints with additional commands that simplify particular tasks.\nThe main usage pattern is listed here:\n$ kcadm.sh create ENDPOINT [ARGUMENTS]\n$ kcadm.sh get ENDPOINT [ARGUMENTS]\n$ kcadm.sh update ENDPOINT [ARGUMENTS]\n$ kcadm.sh delete ENDPOINT [ARGUMENTS]\nThe create, get, update, and delete commands map to the HTTP verbs POST, GET, PUT, and DELETE, respectively. ENDPOINT is a target resource URI and can be absolute (starting with http: or https:) or relative, that Keycloak uses to compose absolute URLs in the following format:\nSERVER_URI/admin/realms/REALM/ENDPOINT\nFor example, if you authenticate against the server http://localhost:8080 and realm is master, using users as ENDPOINT creates the http://localhost:8080/admin/realms/master/users resource URL.\nIf you set ENDPOINT to clients, the effective resource URI is http://localhost:8080/admin/realms/master/clients.\nKeycloak has a realms endpoint that is the container for realms. It resolves to:\nSERVER_URI/admin/realms\nKeycloak has a serverinfo endpoint. This endpoint is independent of realms.\nWhen you authenticate as a user with realm-admin powers, you may need to perform commands on multiple realms. If so, specify the -r option to tell the CLI which realm the command is to execute against explicitly. Instead of using REALM as specified by the --realm option of kcadm.sh config credentials, the command uses TARGET_REALM.\nSERVER_URI/admin/realms/TARGET_REALM/ENDPOINT\nFor example:\n$ kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin\n$ kcadm.sh create users -s username=testuser -s enabled=true -r demorealm\nIn this example, you start a session authenticated as the admin user in the master realm. You then perform a POST call against the resource URL http://localhost:8080/admin/realms/demorealm/users.\nThe create and update commands send a JSON body to the server. You can use -f FILENAME to read a pre-made"},
  {"id": "realm-operations", "title": "Realm operations", "breadcrumb": ["Admin CLI"], "url": "index.html#realm-operations", "md": "md/realm-operations.md", "text": "Creating a new realm\nUse the create command on the realms endpoint to create a new enabled realm. Set the attributes to realm and enabled.\n$ kcadm.sh create realms -s realm=demorealm -s enabled=true\nKeycloak disables realms by default. You can use a realm immediately for authentication by enabling it.\nA description for a new object can also be in JSON format.\n$ kcadm.sh create realms -f demorealm.json\nYou can send a JSON document with realm attributes directly from a file or pipe the document to standard input.\nFor example:\nLinux:\n$ kcadm.sh create realms -f - << EOF\n{ \"realm\": \"demorealm\", \"enabled\": true }\nEOF\nWindows:\nc:\\> echo { \"realm\": \"demorealm\", \"enabled\": true } | kcadm create realms -f -\nListing existing realms\nThis command returns a list of all realms.\n$ kcadm.sh get realms\nKeycloak filters the list of realms on the server to return realms a user can see only.\nThe list of all realm attributes can be verbose, and most users are interested in a subset of attributes, such as the realm name and the enabled status of the realm. You can specify the attributes to return by using the --fields option.\n$ kcadm.sh get realms --fields realm,enabled\nYou can display the result as comma-separated values.\n$ kcadm.sh get realms --fields realm --format csv --noquotes\nGetting a specific realm\nAppend a realm name to a collection URI to get an individual realm.\n$ kcadm.sh get realms/master\nUpdating a realm\nUse the -s option to set new values for the attributes when you do not want to change all of the realm’s attributes.\nFor example:\n$ kcadm.sh update realms/demorealm -s enabled=false\nIf you want to set all writable attributes to new values:\nRun a get command.\nEdit the current values in the JSON file.\nResubmit.\nFor example:\n$ kcadm.sh get realms/demorealm > demorealm.json\n$ vi demorealm.json\n$ kcadm.sh update realms/demorealm -f demorealm.json\nDeleting a realm\nRun the following command to delete a realm:\n$ kcadm.sh delete realms/demorealm\nTurning on all login page options"},
  {"id": "role-operations", "title": "Role operations", "breadcrumb": ["Admin CLI"], "url": "index.html#role-operations", "md": "md/role-operations.md", "text": "Creating a realm role\nUse the roles endpoint to create a realm role.\n$ kcadm.sh create roles -r demorealm -s name=user -s 'description=Regular user with a limited set of permissions'\nCreating a client role\nIdentify the client.\nUse the get command to list the available clients.\n$ kcadm.sh get clients -r demorealm --fields id,clientId\nCreate a new role by using the clientId attribute to construct an endpoint URI, such as clients/ID/roles.\nFor example:\n$ kcadm.sh create clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles -r demorealm -s name=editor -s 'description=Editor can edit, and publish any article'\nListing realm roles\nUse the get command on the roles endpoint to list existing realm roles.\n$ kcadm.sh get roles -r demorealm\nYou can use the get-roles command also.\n$ kcadm.sh get-roles -r demorealm\nListing client roles\nKeycloak has a dedicated get-roles command to simplify the listing of realm and client roles. The command is an extension of the get command and behaves the same as the get command but with additional semantics for listing roles.\nUse the get-roles command by passing it the clientId (--cclientid) option or the id (--cid) option to identify the client to list client roles.\nFor example:\n$ kcadm.sh get-roles -r demorealm --cclientid realm-management\nGetting a specific realm role\nUse the get command and the role name to construct an endpoint URI for a specific realm role, roles/ROLE_NAME, where user is the existing role’s name.\nFor example:\n$ kcadm.sh get roles/user -r demorealm\nYou can use the get-roles command, passing it a role name (--rolename option) or ID (--roleid option).\nFor example:\n$ kcadm.sh get-roles -r demorealm --rolename user\nGetting a specific client role\nUse the get-roles command, passing it the clientId attribute (--cclientid option) or ID attribute (--cid option) to identify the client, and pass the role name (--rolename option) or the role ID attribute (--roleid) to identify a specific client role.\nFor example:\n$ kcadm.sh get-roles -r"},
  {"id": "client-operations", "title": "Client operations", "breadcrumb": ["Admin CLI"], "url": "index.html#client-operations", "md": "md/client-operations.md", "text": "Creating a client\nRun the create command on a clients endpoint to create a new client.\nFor example:\n$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true\nSpecify a secret if to set a secret for adapters to authenticate.\nFor example:\n$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true -s clientAuthenticatorType=client-secret -s secret=d0b8122f-8dfb-46b7-b68a-f5cc4e25d000\nListing clients\nUse the get command on the clients endpoint to list clients.\nThis example filters the output to list only the id and clientId attributes:\n$ kcadm.sh get clients -r demorealm --fields id,clientId\nGetting a specific client\nUse the client ID to construct an endpoint URI that targets a specific client, such as clients/ID.\nFor example:\n$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm\nGetting the current secret for a specific client\nUse the client ID to construct an endpoint URI, such as clients/ID/client-secret.\nFor example:\n$ kcadm.sh get clients/$CID/client-secret -r demorealm\nGenerate a new secret for a specific client\nUse the client ID to construct an endpoint URI, such as clients/ID/client-secret.\nFor example:\n$ kcadm.sh create clients/$CID/client-secret -r demorealm\nUpdating the current secret for a specific client\nUse the client ID to construct an endpoint URI, such as clients/ID.\nFor example:\n$ kcadm.sh update clients/$CID -s \"secret=newSecret\" -r demorealm\nGetting an adapter configuration file (keycloak.json) for a specific client\nUse the client ID to construct an endpoint URI that targets a specific client, such as clients/ID/installation/providers/keycloak-oidc-keycloak-json.\nFor example:\n$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-keycloak-json -r demorealm\nGetting a WildFly subsystem adapter configuration for a specific client\nUse the client ID to construct an endpoint URI that targets a specific client, such as"},
  {"id": "user-operations", "title": "User operations", "breadcrumb": ["Admin CLI"], "url": "index.html#user-operations", "md": "md/user-operations.md", "text": "Creating a user\nRun the create command on the users endpoint to create a new user.\nFor example:\n$ kcadm.sh create users -r demorealm -s username=testuser -s enabled=true\nListing users\nUse the users endpoint to list users. The target user must change their password the next time they log in.\nFor example:\n$ kcadm.sh get users -r demorealm --offset 0 --limit 1000\nYou can filter users by username, firstName, lastName, or email.\nFor example:\n$ kcadm.sh get users -r demorealm -q q=email:google.com\n$ kcadm.sh get users -r demorealm -q q=username:testuser\nFiltering does not use exact matching. This example matches the value of the username attribute against the *testuser* pattern.\nFor clients, groups, and users you can filter across multiple attributes by specifying a more complex q query parameter. you may use something like -q q=\"field1:value1 field2:value2\". Keycloak returns users that match the condition for all the attributes only.\nGetting a specific user\nUse the user ID to compose an endpoint URI, such as users/USER_ID.\nFor example:\n$ kcadm.sh get users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm\nUpdating a user\nUse the update command with the same endpoint URI that you use to get a specific user.\nFor example:\nLinux:\n$ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s 'requiredActions=[\"VERIFY_EMAIL\",\"UPDATE_PROFILE\",\"CONFIGURE_TOTP\",\"UPDATE_PASSWORD\"]'\nWindows:\nc:\\> kcadm update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s \"requiredActions=[\\\"VERIFY_EMAIL\\\",\\\"UPDATE_PROFILE\\\",\\\"CONFIGURE_TOTP\\\",\\\"UPDATE_PASSWORD\\\"]\"\nDeleting a user\nUse the delete command with the same endpoint URI that you use to get a specific user.\nFor example:\n$ kcadm.sh delete users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm\nResetting a user’s password\nUse the dedicated set-password command to reset a user’s password.\nFor example:\n$ kcadm.sh set-password -r demorealm --username testuser --new-password NEWPASSWORD --temporary\nThis command"},
  {"id": "_group_operations", "title": "Group operations", "breadcrumb": ["Admin CLI"], "url": "index.html#_group_operations", "md": "md/_group_operations.md", "text": "Creating a group\nUse the create command on the groups endpoint to create a new group.\nFor example:\n$ kcadm.sh create groups -r demorealm -s name=Group\nListing groups\nUse the get command on the groups endpoint to list groups.\nFor example:\n$ kcadm.sh get groups -r demorealm\nGetting a specific group\nUse the group’s ID to construct an endpoint URI, such as groups/GROUP_ID.\nFor example:\n$ kcadm.sh get groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm\nUpdating a group\nUse the update command with the same endpoint URI that you use to get a specific group.\nFor example:\n$ kcadm.sh update groups/51204821-0580-46db-8f2d-27106c6b5ded -s 'attributes.email=[\"group@example.com\"]' -r demorealm\nDeleting a group\nUse the delete command with the same endpoint URI that you use to get a specific group.\nFor example:\n$ kcadm.sh delete groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm\nCreating a subgroup\nFind the ID of the parent group by listing groups. Use that ID to construct an endpoint URI, such as groups/GROUP_ID/children.\nFor example:\n$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s name=SubGroup\nMoving a group under another group\nFind the ID of an existing parent group and the ID of an existing child group.\nUse the parent group’s ID to construct an endpoint URI, such as groups/PARENT_GROUP_ID/children.\nRun the create command on this endpoint and pass the child group’s ID as a JSON body.\nFor example:\n$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s id=08d410c6-d585-4059-bb07-54dcb92c5094 -s name=SubGroup\nGet groups for a specific user\nUse a user’s ID to determine a user’s membership in groups to compose an endpoint URI, such as users/USER_ID/groups.\nFor example:\n$ kcadm.sh get users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups -r demorealm\nAdding a user to a group\nUse the update command with an endpoint URI composed of a user’s ID and a group’s ID, such as"},
  {"id": "identity-provider-operations", "title": "Identity provider operations", "breadcrumb": ["Admin CLI"], "url": "index.html#identity-provider-operations", "md": "md/identity-provider-operations.md", "text": "Listing available identity providers\nUse the serverinfo endpoint to list available identity providers.\nFor example:\n$ kcadm.sh get serverinfo -r demorealm --fields 'identityProviders(*)'\nKeycloak processes the serverinfo endpoint similarly to the realms endpoint. Keycloak does not resolve the endpoint relative to a target realm because it exists outside any specific realm.\nListing configured identity providers\nUse the identity-provider/instances endpoint.\nFor example:\n$ kcadm.sh get identity-provider/instances -r demorealm --fields alias,providerId,enabled\nGetting a specific configured identity provider\nUse the identity provider’s alias attribute to construct an endpoint URI, such as identity-provider/instances/ALIAS, to get a specific identity provider.\nFor example:\n$ kcadm.sh get identity-provider/instances/facebook -r demorealm\nRemoving a specific configured identity provider\nUse the delete command with the same endpoint URI that you use to get a specific configured identity provider to remove a specific configured identity provider.\nFor example:\n$ kcadm.sh delete identity-provider/instances/facebook -r demorealm\nConfiguring a Keycloak OpenID Connect identity provider\nUse keycloak-oidc as the providerId when you create a new identity provider instance.\nProvide the config attributes: authorizationUrl, tokenUrl, clientId, and clientSecret.\nFor example:\n$ kcadm.sh create identity-provider/instances -r demorealm -s alias=keycloak-oidc -s providerId=keycloak-oidc -s enabled=true -s 'config.useJwksUrl=\"true\"' -s config.authorizationUrl=http://localhost:8180/realms/demorealm/protocol/openid-connect/auth -s config.tokenUrl=http://localhost:8180/realms/demorealm/protocol/openid-connect/token -s config.clientId=demo-oidc-provider -s config.clientSecret=secret\nConfiguring an OpenID Connect identity provider\nConfigure the generic OpenID Connect provider the same way you configure the Keycloak OpenID Connect provider, except you set the providerId attribute value to oidc."},
  {"id": "storage-provider-operations", "title": "Storage provider operations", "breadcrumb": ["Admin CLI"], "url": "index.html#storage-provider-operations", "md": "md/storage-provider-operations.md", "text": "Configuring a Kerberos storage provider\nUse the create command against the components endpoint.\nSpecify the realm id as a value of the parentId attribute.\nSpecify kerberos as the value of the providerId attribute, and org.keycloak.storage.UserStorageProvider as the value of the providerType attribute.\nFor example:\n$ kcadm.sh create components -r demorealm -s parentId=demorealmId -s id=demokerberos -s name=demokerberos -s providerId=kerberos -s providerType=org.keycloak.storage.UserStorageProvider -s 'config.priority=[\"0\"]' -s 'config.debug=[\"false\"]' -s 'config.allowPasswordAuthentication=[\"true\"]' -s 'config.editMode=[\"UNSYNCED\"]' -s 'config.updateProfileFirstLogin=[\"true\"]' -s 'config.allowKerberosAuthentication=[\"true\"]' -s 'config.kerberosRealm=[\"KEYCLOAK.ORG\"]' -s 'config.keyTab=[\"http.keytab\"]' -s 'config.serverPrincipal=[\"HTTP/localhost@KEYCLOAK.ORG\"]' -s 'config.cachePolicy=[\"DEFAULT\"]'\nConfiguring an LDAP user storage provider\nUse the create command against the components endpoint.\nSpecify ldap as the value of the providerId attribute, and org.keycloak.storage.UserStorageProvider as the value of the providerType attribute.\nProvide the realm ID as the value of the parentId attribute.\nUse the following example to create a Kerberos-integrated LDAP provider.\n$ kcadm.sh create components -r demorealm -s name=kerberos-ldap-provider -s providerId=ldap -s providerType=org.keycloak.storage.UserStorageProvider -s parentId=3d9c572b-8f33-483f-98a6-8bb421667867  -s 'config.priority=[\"1\"]' -s 'config.fullSyncPeriod=[\"-1\"]' -s 'config.changedSyncPeriod=[\"-1\"]' -s 'config.cachePolicy=[\"DEFAULT\"]' -s config.evictionDay=[] -s config.evictionHour=[] -s config.evictionMinute=[] -s config.maxLifespan=[] -s 'config.batchSizeForSync=[\"1000\"]' -s 'config.editMode=[\"WRITABLE\"]' -s 'config.syncRegistrations=[\"false\"]' -s 'config.vendor=[\"other\"]' -s 'config.usernameLDAPAttribute=[\"uid\"]' -s 'config.rdnLDAPAttribute=[\"uid\"]' -s 'config.uuidLDAPAttribute=[\"entryUUID\"]' -s"},
  {"id": "adding-mappers", "title": "Adding mappers", "breadcrumb": ["Admin CLI"], "url": "index.html#adding-mappers", "md": "md/adding-mappers.md", "text": "Adding a hard-coded role LDAP mapper\nRun the create command on the components endpoint.\nSet the providerType attribute to org.keycloak.storage.ldap.mappers.LDAPStorageMapper.\nSet the parentId attribute to the ID of the LDAP provider instance.\nSet the providerId attribute to hardcoded-ldap-role-mapper. Ensure you provide a value of role configuration parameter.\nFor example:\n$ kcadm.sh create components -r demorealm -s name=hardcoded-ldap-role-mapper -s providerId=hardcoded-ldap-role-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config.role=[\"realm-management.create-client\"]'\nAdding an MS Active Directory mapper\nRun the create command on the components endpoint.\nSet the providerType attribute to org.keycloak.storage.ldap.mappers.LDAPStorageMapper.\nSet the parentId attribute to the ID of the LDAP provider instance.\nSet the providerId attribute to msad-user-account-control-mapper.\nFor example:\n$ kcadm.sh create components -r demorealm -s name=msad-user-account-control-mapper -s providerId=msad-user-account-control-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea\nAdding a user attribute LDAP mapper\nRun the create command on the components endpoint.\nSet the providerType attribute to org.keycloak.storage.ldap.mappers.LDAPStorageMapper.\nSet the parentId attribute to the ID of the LDAP provider instance.\nSet the providerId attribute to user-attribute-ldap-mapper.\nFor example:\n$ kcadm.sh create components -r demorealm -s name=user-attribute-ldap-mapper -s providerId=user-attribute-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config.\"user.model.attribute\"=[\"email\"]' -s 'config.\"ldap.attribute\"=[\"mail\"]' -s 'config.\"read.only\"=[\"false\"]' -s 'config.\"always.read.value.from.ldap\"=[\"false\"]' -s 'config.\"is.mandatory.in.ldap\"=[\"false\"]'"},
  {"id": "authentication-operations", "title": "Authentication operations", "breadcrumb": ["Admin CLI"], "url": "index.html#authentication-operations", "md": "md/authentication-operations.md", "text": "Setting a password policy\nSet the realm’s passwordPolicy attribute to an enumeration expression that includes the specific policy provider ID and optional configuration.\nUse the following example to set a password policy to default values. The default values include:\n210,000 hashing iterations\nat least one special character\nat least one uppercase character\nat least one digit character\nnot be equal to a user’s username\nbe at least eight characters long\n$ kcadm.sh update realms/demorealm -s 'passwordPolicy=\"hashIterations and specialChars and upperCase and digits and notUsername and length\"'\nTo use values different from defaults, pass the configuration in brackets.\nUse the following example to set a password policy to:\n300,000 hash iterations\nat least two special characters\nat least two uppercase characters\nat least two lowercase characters\nat least two digits\nbe at least nine characters long\nnot be equal to a user’s username\nnot repeat for at least four changes back\n$ kcadm.sh update realms/demorealm -s 'passwordPolicy=\"hashIterations(300000) and specialChars(2) and upperCase(2) and lowerCase(2) and digits(2) and length(9) and notUsername and passwordHistory(4)\"'\nObtaining the current password policy\nYou can get the current realm configuration by filtering all output except for the passwordPolicy attribute.\nFor example, display passwordPolicy for demorealm.\n$ kcadm.sh get realms/demorealm --fields passwordPolicy\nListing authentication flows\nRun the get command on the authentication/flows endpoint.\nFor example:\n$ kcadm.sh get authentication/flows -r demorealm\nGetting a specific authentication flow\nRun the get command on the authentication/flows/FLOW_ID endpoint.\nFor example:\n$ kcadm.sh get authentication/flows/febfd772-e1a1-42fb-b8ae-00c0566fafb8 -r demorealm\nListing executions for a flow\nRun the get command on the authentication/flows/FLOW_ALIAS/executions endpoint.\nFor example:\n$ kcadm.sh get authentication/flows/Copy%20of%20browser/executions -r demorealm"}
]