Configure OIDC Authentication with Keycloak (2023)

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

overview

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

Tent

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.