<titledata-rh="true">Keycloak OIDC | OAuth2 Proxy</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://oauth2-proxy.github.io/oauth2-proxy/docs/next/configuration/providers/keycloak_oidc"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="Keycloak OIDC | OAuth2 Proxy"><metadata-rh="true"name="description"content="Keycloak has updated its admin console and as of version 19.0.0, the new admin console is enabled by default. The"><metadata-rh="true"property="og:description"content="Keycloak has updated its admin console and as of version 19.0.0, the new admin console is enabled by default. The"><linkdata-rh="true"rel="icon"href="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg"><linkdata-rh="true"rel="canonical"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/next/configuration/providers/keycloak_oidc"><linkdata-rh="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/next/configuration/providers/keycloak_oidc"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/next/configuration/providers/keycloak_oidc"hreflang="x-default"><linkrel="stylesheet"href="/oauth2-proxy/assets/css/styles.4014daec.css">
legacy admin console has been announced for removal with the release of version 21.0.0.</p></div></div><p><strong>Keycloak legacy admin console</strong></p><ol><li>Create new client in your Keycloak realm with <strong>Access Type</strong>'confidential', <strong>Client protocol</strong>'openid-connect'
and <strong>Valid Redirect URIs</strong>'<ahref="https://internal.yourcompany.com/oauth2/callback'"target="_blank"rel="noopener noreferrer">https://internal.yourcompany.com/oauth2/callback'</a></li><li>Take note of the Secret in the credential tab of the client</li><li>Create a mapper with <strong>Mapper Type</strong>'Group Membership' and <strong>Token Claim Name</strong>'groups'.</li><li>Create a mapper with <strong>Mapper Type</strong>'Audience' and <strong>Included Client Audience</strong> and <strong>Included Custom Audience</strong> set
to your client name.</li></ol><p><strong>Keycloak new admin console (default as of v19.0.0)</strong></p><p>The following example shows how to create a simple OIDC client using the new Keycloak admin2 console. However, for best
practices, it is recommended to consult the Keycloak documentation.</p><p>The OIDC client must be configured with an <em>audience mapper</em> to include the client's name in the <code>aud</code> claim of the JWT token.<br>
<!---->The <code>aud</code> claim specifies the intended recipient of the token, and OAuth2 Proxy expects a match against the values of
either <code>--client-id</code> or <code>--oidc-extra-audience</code>.</p><p><em>In Keycloak, claims are added to JWT tokens through the use of mappers at either the realm level using "client scopes" or
through "dedicated" client mappers.</em></p><p><strong>Creating the client</strong></p><ol><li>Create a new OIDC client in your Keycloak realm by navigating to:<br><strong>Clients</strong> -><strong>Create client</strong><ul><li><strong>Client Type</strong>'OpenID Connect'</li><li><strong>Client ID</strong><code><your client's id></code>, please complete the remaining fields as appropriate and click <strong>Next</strong>.<ul><li><strong>Client authentication</strong>'On'</li><li><strong>Authentication flow</strong><ul><li><strong>Standard flow</strong>'selected'</li><li><strong>Direct access grants</strong>'deselect'<ul><li><em>Save the configuration.</em></li></ul></li></ul></li><li><strong>Settings / Access settings</strong>:<ul><li><strong>Valid redirect URIs</strong><code>https://internal.yourcompany.com/oauth2/callback</code><ul><li><em>Save the configuration.</em></li></ul></li></ul></li><li>Under the <strong>Credentials</strong> tab you will now be able to locate <code><your client's secret></code>.</li></ul></li></ul></li><li>Configure a dedicated <em>audience mapper</em> for your client by navigating to <strong>Clients</strong> -><strong><your client's id></strong> -><strong>Client scopes</strong>.</li></ol><ul><li>Access the dedicated mappers pane by clicking <strong><your client's id>-dedicated</strong>, located under <em>Assigned client scope</em>.<br><em>(It should have a description of "Dedicated scope and mappers for this client")</em><ul><li>Click <strong>Configure a new mapper</strong> and select <strong>Audience</strong><ul><li><strong>Name</strong>'aud-mapper-<your client's id>'</li><li><strong>Included Client Audience</strong> select <code><your client's id></code> from the dropdown.<ul><li><em>OAuth2 proxy can be set up to pass both the access and ID JWT tokens to your upstream services.
If you require additional audience entries, you can use the <strong>Included Custom Audience</strong> field in addition
to the "Included Client Audience" dropdown. Note that the "aud" claim of a JWT token should be limited and
only specify its intended recipients.</em></li></ul></li><li><strong>Add to ID token</strong>'On'</li><li><strong>Add to access token</strong>'On' - <ahref="https://github.com/oauth2-proxy/oauth2-proxy/pull/1916"target="_blank"rel="noopener noreferrer">#1916</a><ul><li><em>Save the configuration.</em></li></ul></li></ul></li></ul></li><li>Any subsequent dedicated client mappers can be defined by clicking <strong>Dedicated scopes</strong> -><strong>Add mapper</strong> ->
<strong>By configuration</strong> -><em>Select mapper</em></li></ul><p>You should now be able to create a test user in Keycloak and get access to the OAuth2 Proxy instance, make sure to set
an email address matching <code><yourcompany.com></code> and select <em>Email verified</em>.</p><p><strong>Authorization</strong></p><p><em>OAuth2 Proxy will perform authorization by requiring a valid user, this authorization can be extended to take into
account a user's membership in Keycloak <code>groups</code>, <code>realm roles</code>, and <code>client roles</code> using the keycloak-oidc provider options<br><code>--allowed-role</code> or <code>--allowed-group</code></em></p><p><strong>Roles</strong></p><p><em>A standard Keycloak installation comes with the required mappers for <strong>realm roles</strong> and <strong>client roles</strong> through the
pre-defined client scope "roles". This ensures that any roles assigned to a user are included in the <code>JWT</code> tokens when
using an OIDC client that has the "Full scope allowed" feature activated, the feature is enabled by default.</em></p><p><em>Creating a realm role</em></p><ul><li>Navigate to <strong>Realm roles</strong> -><strong>Create role</strong><ul><li><strong>Role name</strong>, <em><code><realm role name></code></em> -><strong>save</strong></li></ul></li></ul><p><em>Creating a client role</em></p><ul><li>Navigate to <strong>Clients</strong> -><code><your client's id></code> -><strong>Roles</strong> -><strong>Create role</strong><ul><li><strong>Role name</strong>, <em><code><client role name></code></em> -><strong>save</strong></li></ul></li></ul><p><em>Assign a role to a user</em></p><p><strong>Users</strong> -><em>Username</em> -><strong>Role mapping</strong> -><strong>Assign role</strong> -><em>filter by roles or clients and select</em> -><strong>Assign</strong>.</p><p>Keycloak "realm roles" can be authorized using the <code>--allowed-role=<realm role name></code> option, while "client roles" can be
evaluated using <code>--allowed-role=<your client's id>:<client role name></code>.</p><p>You may limit the <em>realm roles</em> included in the JWT tokens for any given client by navigating to:<br>
<!---->Disabling <strong>Full scope allowed</strong> activates the <strong>Assign role</strong> option, allowing you to select which roles, if assigned
to a user, will be included in the user's JWT tokens. This can be useful when a user has many associated roles, and you
want to reduce the size and impact of the JWT token.</p><p><strong>Groups</strong></p><p>You may also do authorization on group memberships by using the OAuth2 Proxy option <code>--allowed-group</code>.<br>
<!---->We will only do a brief description of creating the required <em>client scope</em><strong>groups</strong> and refer you to read the Keycloak
documentation.</p><p>To summarize, the steps required to authorize Keycloak group membership with OAuth2 Proxy are as follows:</p><ul><li>Create a new Client Scope with the name <strong>groups</strong> in Keycloak.<ul><li>Include a mapper of type <strong>Group Membership</strong>.</li><li>Set the "Token Claim Name" to <strong>groups</strong> or customize by matching it to the <code>--oidc-groups-claim</code> option of OAuth2 Proxy.</li><li>If the "Full group path" option is selected, you need to include a "/" separator in the group names defined in the
<code>--allowed-group</code> option of OAuth2 Proxy. Example: "/groupname" or "/groupname/child_group".</li></ul></li></ul><p>After creating the <em>Client Scope</em> named <em>groups</em> you will need to attach it to your client.<br>
and you should now have a client that maps group memberships into the JWT tokens so that Oauth2 Proxy may evaluate them.</p><p>Create a group by navigating to <strong>Groups</strong> -><strong>Create group</strong> and <em>add</em> your test user as a member.</p><p>The OAuth2 Proxy option <code>--allowed-group=/groupname</code> will now allow you to filter on group membership</p><p>Keycloak also has the option of attaching roles to groups, please refer to the Keycloak documentation for more information.</p><p><strong>Tip</strong></p><p>To check if roles or groups are added to JWT tokens, you can preview a users token in the Keycloak console by following
these steps: <strong>Clients</strong> -><code><your client's id></code> -><strong>Client scopes</strong> -><strong>Evaluate</strong>.<br>
<!---->Select a <em>realm user</em> and optional <em>scope parameters</em> such as groups, and generate the JSON representation of an access
