Configure OIDC Authentication with Keycloak (2023)

This guide explains how to configure OpenID Connect (OIDC) with Keycloak as the identity provider.


Complete the steps in this guide to secure the Instance Manager with OpenID Connect (OIDC) using the authorization code flow method andKeychainas an identity provider. As an administrator, by integrating OpenID authentication with Instance Manager, you can use role-based access control (RBAC) to restrict user access to NGINX instances.

before you start

To complete the instructions in this guide, you will need the following:

  • A working Keycloak server. Consult the Keycloak documentation forStartingeServosetup instructions. Youre gonna need itcreate a kingdomwith the OpenID endpoint setting enabled.
  • Install the instance manageraboutNGINX Plus R25 ou posterior.
  • install itNGINX JavaScript module(njs). This module is required to handle interactions between NGINX Plus and the identity provider.

Create user roles and groups in Instance Manager

By default, the Instance Manager includes a single function calledAdministrator. Depending on your requirements, you may need to createadditional functionsfor the different user groups such as "user" and "nap user".

The standardAdministratoruser or any user withTO CREATEpermission touser managementfeature can create a role.

To create a role, follow these steps:

  1. In a web browser, navigate to the NGINX Management Suite host FQDN and connect.

  2. Choicesettingsicon (gear) in the upper right corner.

  3. From the left navigation menu, selectClock.

  4. To chooseTo create.

  5. Nocreate a functionform, provide the following information:

    • Name: the name to use for the function
    • Display name: an optional, user-friendly display name for the role
    • Description: an optional short summary of the role
  6. To add permissions:

    1. To chooseadd license.
    2. NoUnit of measurementlist, select the module for which you are creating a license.
    3. Noresourcelist, select a feature for which you are creating a license.
    4. NoAccesslist, select the level of access you want to grant.
    5. To chooseTo save.
  7. Repeat step 6 to add more permissions for other roles.

  8. After adding all required permissions, selectTo saveto create the function.

Create user groups in Instance Manager, for example "nms-admins", "nms-users" and "nms-nap-users". These user groups will be mapped by Keycloak Realm roles by name.

User pools require an OIDC identity provider
User pools are only used with external identity providers configured for OpenID Connect (OIDC) authentication, as described inAuthentication Setup Wizard. Users from an external identity provider cannot be assigned roles directly in NGINX Management Suite. However, they can inherit roles through their team members.

The standardAdministratoruser or any user withTO CREATEpermission touser managementattribute can create a group.

To create a user group, follow these steps:

  1. In a web browser, navigate to the NGINX Management Suite host FQDN and connect.

  2. Choicesettingsicon (gear) in the upper right corner.

  3. From the left navigation menu, selectuser groups.

  4. To chooseTo create.

  5. NoCreate a TEAMform, enter information about the group:

    • team name: Mandatory. The group name must match the group name in the external identity provider. A group can only report one identity provider.
    • Display name: A friendly display name for the group.
    • Description: A brief summary of the team.
  6. NoClocklist, select one or more roles to assign to the group.

  7. To chooseTo saveto create the group.

Configure Keycloak

Follow these steps to set up the Keycloak.

  1. Log in to Keycloak as an administrator.
  2. From the navigation menu, selectCustomers.
  3. To chooseTo create.
  4. Noadd customershape, inClient IDin the box, type “nms” as the client name.
  5. Noclient protocollist, selectopen connection.
  6. Set it uproot urlto the URL of the NGINX Management Suite instance, for example,https://:443/_codexch.
  7. To chooseTo save.

After creating the client, add the following configuration:

  1. Nosettingsguide, intype of accesslist, selectconfidential.
  2. Nocartographerstab, selectadd integratedand selectgroups. This will extract the user's Keycloak Realm role information for use by NGINX Management Suite.

NGINX Management Suite user groups will be mapped by KeycloakVassiliou's papers; Keycloack client functions arenomapped. Be sure to use higher level Keycloack roles (Realm Roles).

  1. From the navigation menu, selectVassiliou's papers(or chooseClockAnd after thisVassiliou's papersguide if you are on an older version of Keycloak).
  2. To choosecreate a function.
  3. Nopaper namein the box, type the name of the first group created in the Instance Manager, for example "nms-admins".
  4. To chooseTo save.
  5. Repeat steps 1-3 until you have recreated all the groups you want to grant access to, for example "nms-users" and "nms-nap-users".

Create the users that will be allowed to connect to the Instance Manager.

  1. On the navigation bar, selectUsers.
  2. To chooseadd user.
  3. NoUser namebox, type the username.
  4. Noe-mailbox, enter the user's email address. NGINX Management Suite will use this email address as the user ID when defining your headers.
  5. To chooseTo save.
  6. After creating the user, select itCredentialsear.
  7. They provide aPassword, confirm and selectset a password.
  8. NoFunction Mappings, select the desired roles from the list, for example "nms-admins", "nms-users", or "nms-nap-users".
  9. To chooseadd favorites.

Configure NGINX Management Suite to use Keycloak

  • Copy the Keycloak secret and set it as an environment variable in the NGINX Management Suite instance.

    By IU do Keycloak:

    1. ChoiceCustomerstab and select itnmclient.
    2. NoCredentialsguide, copy itSecretvalor.

    In your NGINX Management Suite instance,

    1. Set the following environment variable:export KEYCLOAK_SECRET=;
    2. Update the NGINX Management Suite OIDC configuration with the appropriate values:

Log into your NGINX Management Suite instance and run the following commands:

  • Export the environment variables:

    # FQDN or IP address are appropriate for these environment variables.export KEYCLOAK_IP=""export NMS_IP=""export KEYCLOAK_CLIENT_ID=""export KEYCLOAK_CLIENT_SECRET=""# Select an appropriate hash-based message authentication code (HMAC)export HMAC_KEY=""export KEYCLOAK_AUTH_ENDPOINT=$(curl -mr"http://$KEYCLOAK_IP:8443/auth/realms//.well known/openid configuration" |jq-r".endpoint_authorization")export KEYCLOAK_TOKEN_ENDPOINT=$(curl -mr"http://$KEYCLOAK_IP:8443/auth/realms//.well known/openid configuration" |jq-r".token_endpoint")export KEYCLOAK_KEYS_ENDPOINT=$(curl -mr"http://$KEYCLOAK_IP:8443/auth/realms//.well known/openid configuration" |jq-r".jwks_uri")
  • Back up the original configuration files.

    sudo cp /etc/nms/nginx/oidc/openid_configuration.conf ~/openid_configuration.conf.origsudo cp /etc/nginx/conf.d/nms-http.conf ~/nms-http.conf.orig
  • Copy the OpenID configuration for NGINX to the/tmpto substitute the required values.

    sudo cp /etc/nms/nginx/oidc/openid_configuration.conf /tmp/openid_configuration.confsudo sed -i'.bak' \-m"s%OIDC_CLIENT_ID%${KEYCLOAK_CLIENT_ID}%" \-m"s%SERVER_FQDN%${NMS_IP}%" \-m"s%OIDC_AUTH_ENDPOINT%${KEYCLOAK_AUTH_ENDPOINT}%" \-m"s%OIDC_TOKEN_ENDPOINT%${KEYCLOAK_TOKEN_ENDPOINT}%" \-m"s%OIDC_KEYS_ENDPOINT%${KEYCLOAK_KEYS_ENDPOINT}%" \-m"s%OIDC_CLIENT_SECRET%${KEYCLOAK_CLIENT_SECRET}%" \-m"s%OIDC_HMAC_KEY%${HMAC_KEY}%" \/tmp/openid_configuration.conf
  • Uncomment your section/tmp/openid_configuration.confrequired for Keycloak as in the following example:

    # Enable when using OIDC with keycloakmapa $http_authorization $groups_claim {default $jwt_claim_groups;}mapa $http_authorization $user_email {"~^Bearer.*" '$jwt_clientId@$oidc_domain';default $jwt_claim_email;}
  • Copy the nms-http.conf file to/tmpto substitute the required values.

    sudo cp /etc/nginx/conf.d/nms-http.conf /tmp/nms-http.conf
  • Uncomment OIDC modulesnms-http.confas in the following examples:

    # Enable when using OIDClog_format oidc_jwt '$remote_addr - $jwt_claim_sub [$time_local] "$request" ''$status $body_bytes_sent "$http_referer" "$http_user_agent" ''"$http_x_forwarded_for"';
    # OIDC - Includes client configuration disconnect to enabledoes it include /etc/nms/nginx/oidc/openid_configuration.conf?
    ## For OIDC authentication: authorization code flow and third-party processing# OIDC - uncomment the following instructions for activationadd_header Nginx-Management-Suite-Auth "OIDC";does it include /etc/nms/nginx/oidc/openid_connect.conf?
    # OIDC: use email as unique identifier# NOTE: The username depends on the claims provided by your IdPproxy_set_header Nginx-Management-Suite-Auth "OIDC";proxy_set_header Nginx-Management-Suite-User $user_email;proxy_set_header Nginx-Management-Suite-Groups $groups_claim;proxy_set_header Nginx-Management-Suite-ExternalId $jwt_claim_sub;

    Also, uncomment all sections that begin with# OIDC authentication (uncomment to enable).

  • Comment out all sections of Basic Authnms-http.confas in the following examples:

    ## For use with basic certification#auth_basic_user_file /etc/nms/nginx/.htpasswd;## indicates the type of authentication on the client#add_header Nginx-Management-Suite-Auth "Básico";
    #basic HTTP:#proxy_set_header Nginx-Management-Suite-User $remote_user;#proxy_set_header Nginx-Management-Suite-Groups "";#proxy_set_header Nginx-Management-Suite-ExternalId "";

    Also comment out all sections starting at# Basic HTTP authentication (comment if using OIDC authentication)o# Basic HTTP authentication (disable if using OIDC).

  • Copy the modified configuration files back to their original locations.

    sudo cp /tmp/nms-http.conf /etc/nginx/conf.d/nms-http.confsudo cp /tmp/openid_configuration.conf /etc/nms/nginx/oidc/openid_configuration.conf
  • Runsudo nginx -τto verify that the configuration does not contain errors.

  • Reload NGINX up and runningsudo nginx -s reload.

Problems solution

You can revert to basic authentication to troubleshoot authentication issues by running the following commands:

sudo cp ~/openid_configuration.conf.orig etc/nms/nginx/oidc/openid_configuration.confsudo cp ~/nms-http.conf.orig /etc/nginx/conf.d/nms-http.confsudo nginx -s reload


Open the Instance Manager by going tohttps:///ui.

You should be redirected to the Keycloak login page. Log in with the credentials you created in Keycloak.


Configure OIDC Authentication with Keycloak? ›

Configure OpenID Connect - Keycloak

OpenID Connect is an extension to OAuth2, so we use a OAuth2 connector to create the connection and OIDC handler. You explore the OpenID Connect service discover endpoint, the Keycloak OpenID Connect discovery endpoint is available here: localhost:8989/realms/dev/.

Does Keycloak use OIDC? ›

Configure OpenID Connect - Keycloak

OpenID Connect is an extension to OAuth2, so we use a OAuth2 connector to create the connection and OIDC handler. You explore the OpenID Connect service discover endpoint, the Keycloak OpenID Connect discovery endpoint is available here: localhost:8989/realms/dev/.

How do I authenticate with OIDC? ›

The OIDC specification states that authentication can follow one of three paths: the Authorization Code Flow, the Implicit Flow, or the Hybrid Flow. The flow determines how the ID Token and Access Token are returned to the Client.

How do you authenticate with a Keycloak? ›

Configure Keycloak to authenticate your cbioportal instance. Log in to your Keycloak Identity Provider, e.g. http://localhost:8080/auth, as an admin user. ⚠️ when setting this up on something else than localhost (e.g. production), you will need to use/enable https on your Keycloak server.

Does Keycloak use SAML or OpenID? ›

Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML). In most cases Keycloak recommends using OIDC. SAML tends to be a bit more verbose than OIDC.

How do I add OIDC client to Keycloak? ›

  1. To create an OIDC client go to the Clients left menu item. On this page you'll see a Create button on the right. ...
  2. This will bring you to the Add Client page. Add Client.
  3. Enter in the Client ID of the client.

Does OIDC require JWT? ›

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 framework. It allows third-party applications to verify the identity of the end-user and to obtain basic user profile information. OIDC uses JSON web tokens (JWTs), which you can obtain using flows conforming to the OAuth 2.0 specifications.

What is the difference between OpenID Connect and OIDC? ›

OIDC uses JSON Web Tokens (JWT), HTTP flows and avoids sharing user credentials with services. OpenID Connect has consent built-in. This is important as OIDC is often used in consumer-facing services (e.g., a Relying Party), where the sharing of personal data requires the user's explicit consent.

Is OIDC for authentication or authorization? ›

OpenID Connect (OIDC) is an open authentication protocol that works on top of the OAuth 2.0 framework. Targeted toward consumers, OIDC allows individuals to use single sign-on (SSO) to access relying party sites using OpenID Providers (OPs), such as an email provider or social network, to authenticate their identities.

What is the difference between SAML and OIDC authentication? ›

OIDC is lightweight and more performance-friendly than SAML. For large enterprises that require a higher level of security, SAML might be the better choice. SAML allows multi-factor authentication. It is a more mature standard with a proven track record and more feature-rich than OIDC.

Is Keycloak outdated? ›

The Keycloak Java adapters will remain for a while though, at least towards the end of the year, but likely not be removed until early 2024. At the same time don't expect the adapters to be updated in terms of adding new features, enhancements, or supporting newer versions of Tomcat, Jetty, WildFly, or Spring.

What type of authentication does Keycloak use? ›


Keycloak provides support for clients to authenticate either with a secret or with public/private keys. For more details, see the Client Credentials Grant chapter in the OAuth 2.0 specification.

How does Keycloak OpenID Connect work? ›

The most common way to authenticate a user with Keycloak is through the OpenID Connect authorization code flow. 1- The user clicks on a login button in the application. 2- The application generates an authentication request. 3- The authentication request is sent to the user with a 302 redirect.

Is Keycloak authentication or authorization? ›

Keycloak provides a range of features to help organizations manage user authentication, user authorization, and user management. Here are some of the key features: Single Sign-On (SSO): Keycloak provides SSO functionality, which means users only need to authenticate once to access multiple applications.

Is Keycloak an OAuth server? ›

Keycloak is an open source identity and access management (IAM) tool. It can overwrite and customize almost every aspect of a product or module. It implements almost all standard IAM protocols, including OAuth 2.0, OpenID, and SAML.

What types of authentication does Keycloak use? ›


This example demonstrates three different ways of establishing authentication using Keycloak: using a public client, confidential client, and service account. You can choose among the following functions to suit your requirement, depending on the type of authentication you want.

What protocol does Keycloak use? ›

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.

Is Keycloak based on oauth2? ›

Keycloak is an open source identity and access management (IAM) tool. It can overwrite and customize almost every aspect of a product or module. It implements almost all standard IAM protocols, including OAuth 2.0, OpenID, and SAML.

Does Keycloak use SAML? ›

The JBoss KeyCloak system is a widely used and open-source identity management system that supports integration with applications via SAML and OpenID Connect.


Top Articles
Latest Posts
Article information

Author: Duane Harber

Last Updated: 29/06/2023

Views: 6079

Rating: 4 / 5 (51 voted)

Reviews: 90% of readers found this page helpful

Author information

Name: Duane Harber

Birthday: 1999-10-17

Address: Apt. 404 9899 Magnolia Roads, Port Royceville, ID 78186

Phone: +186911129794335

Job: Human Hospitality Planner

Hobby: Listening to music, Orienteering, Knapping, Dance, Mountain biking, Fishing, Pottery

Introduction: My name is Duane Harber, I am a modern, clever, handsome, fair, agreeable, inexpensive, beautiful person who loves writing and wants to share my knowledge and understanding with you.