From 8e2ecdd0439b18576e2cbd7a14ba6fb89186e02b Mon Sep 17 00:00:00 2001 From: Micheal Kingston <44472403+mkingst@users.noreply.github.com> Date: Mon, 6 Jan 2025 12:57:03 +0000 Subject: [PATCH 1/2] Update keycloak-setup.md for Keycloak > 18 --- .../authentication/oidc/keycloak-setup.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/content/nim/admin-guide/authentication/oidc/keycloak-setup.md b/content/nim/admin-guide/authentication/oidc/keycloak-setup.md index cfc661138..01c390db7 100644 --- a/content/nim/admin-guide/authentication/oidc/keycloak-setup.md +++ b/content/nim/admin-guide/authentication/oidc/keycloak-setup.md @@ -47,9 +47,16 @@ Follow these steps to configure Keycloak. After the client is created, configure it as follows: +If Keycloak is version < 18.x + 1. On the **Settings** tab, in the **Access Type** list, select **confidential**. 2. On the **Mappers** tab, select **Add Builtin**, and select **groups**. This exports the user's Keycloak Realm Role information for NGINX Instance Manager to use. +If Keycloak is version >= 18.x + +1. On the **Settings** tab, enable the **Client authentication** toggle under the Capability config. Also, enable the **Direct Access Grants** and **Service Account** roles in the **Authentication flow** section. +2. Select the **Client Scopes** tab, under the list of scopes click on the scope with the name **-dedicated (nim-dedicated)**. Under the **Mappers** tab, click **Configure new Mapper** and select **From predefined mappers**. In the **Add predefined mappers** section, search for **groups** mapper and select **Add groups mapper**. + ### Create Keycloak Roles NGINX Instance Manager User Groups will map to Keycloak **Realm Roles**; Keycloak Client Roles are **not** mapped. Use Keycloak top-level roles (Realm Roles). @@ -119,6 +126,8 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - Export the environment variables: +If Keycloak is version < 18.x: + ```bash # Either the FQDN or the IP address is suitable for these environment variables. export KEYCLOAK_IP="" @@ -134,6 +143,23 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the export KEYCLOAK_KEYS_ENDPOINT=$(curl -k "https://$KEYCLOAK_IP:8443/auth/realms//.well-known/openid-configuration" | jq -r ".jwks_uri") ``` +If Keycloak is version >= 18.x (‘/auth’ path is no longer needed): + + ```bash + # Either the FQDN or the IP address is suitable for these environment variables. + export KEYCLOAK_IP="" + export NIM_IP="" + export KEYCLOAK_CLIENT_ID="" + export KEYCLOAK_CLIENT_SECRET="" + + # Choose an appropriate Hash-Based Message Authentication Code (HMAC) + export HMAC_KEY="" + + export KEYCLOAK_AUTH_ENDPOINT=$(curl -k “https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration” | jq -r “.authorization_endpoint”) + export KEYCLOAK_TOKEN_ENDPOINT=$(curl -k “https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration” | jq -r “.token_endpoint”) + export KEYCLOAK_KEYS_ENDPOINT=$(curl -k “https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration” | jq -r “.jwks_uri”) + ``` + - Back up the original configuration files: ```bash From f7a6825db8839e4b370f584e56a9e24e66d48217 Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Mon, 6 Jan 2025 08:48:37 -0800 Subject: [PATCH 2/2] formatting edits --- .../authentication/oidc/keycloak-setup.md | 34 +++++++++++++------ 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/content/nim/admin-guide/authentication/oidc/keycloak-setup.md b/content/nim/admin-guide/authentication/oidc/keycloak-setup.md index 01c390db7..919a7012a 100644 --- a/content/nim/admin-guide/authentication/oidc/keycloak-setup.md +++ b/content/nim/admin-guide/authentication/oidc/keycloak-setup.md @@ -47,15 +47,19 @@ Follow these steps to configure Keycloak. After the client is created, configure it as follows: -If Keycloak is version < 18.x +#### For Keycloak versions earlier than 18.x -1. On the **Settings** tab, in the **Access Type** list, select **confidential**. -2. On the **Mappers** tab, select **Add Builtin**, and select **groups**. This exports the user's Keycloak Realm Role information for NGINX Instance Manager to use. +1. On the **Settings** tab, set **Access Type** to **confidential**. +2. On the **Mappers** tab, select **Add Builtin** and choose **groups** to export Keycloak Realm Role information for NGINX Instance Manager. -If Keycloak is version >= 18.x +#### For Keycloak versions 18.x and later -1. On the **Settings** tab, enable the **Client authentication** toggle under the Capability config. Also, enable the **Direct Access Grants** and **Service Account** roles in the **Authentication flow** section. -2. Select the **Client Scopes** tab, under the list of scopes click on the scope with the name **-dedicated (nim-dedicated)**. Under the **Mappers** tab, click **Configure new Mapper** and select **From predefined mappers**. In the **Add predefined mappers** section, search for **groups** mapper and select **Add groups mapper**. +1. On the **Settings** tab, under **Capability config**, enable **Client authentication**. +2. In the **Authentication flow** section, enable **Direct Access Grants** and **Service Account**. +3. Go to the **Client Scopes** tab. + - Select the scope named **-dedicated (nim-dedicated)**. + - On the **Mappers** tab, click **Configure new Mapper** and choose **From predefined mappers**. + - Search for **groups** and select **Add groups mapper**. ### Create Keycloak Roles @@ -126,7 +130,7 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - Export the environment variables: -If Keycloak is version < 18.x: + - **For Keycloak versions earlier than 18.x**: ```bash # Either the FQDN or the IP address is suitable for these environment variables. @@ -143,7 +147,7 @@ If Keycloak is version < 18.x: export KEYCLOAK_KEYS_ENDPOINT=$(curl -k "https://$KEYCLOAK_IP:8443/auth/realms//.well-known/openid-configuration" | jq -r ".jwks_uri") ``` -If Keycloak is version >= 18.x (‘/auth’ path is no longer needed): + - **For Keycloak versions 18.x and later**: ```bash # Either the FQDN or the IP address is suitable for these environment variables. @@ -155,9 +159,17 @@ If Keycloak is version >= 18.x (‘/auth’ path is no longer needed): # Choose an appropriate Hash-Based Message Authentication Code (HMAC) export HMAC_KEY="" - export KEYCLOAK_AUTH_ENDPOINT=$(curl -k “https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration” | jq -r “.authorization_endpoint”) - export KEYCLOAK_TOKEN_ENDPOINT=$(curl -k “https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration” | jq -r “.token_endpoint”) - export KEYCLOAK_KEYS_ENDPOINT=$(curl -k “https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration” | jq -r “.jwks_uri”) + export KEYCLOAK_AUTH_ENDPOINT=$(curl -k \ + "https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration" | \ + jq -r ".authorization_endpoint") + + export KEYCLOAK_TOKEN_ENDPOINT=$(curl -k \ + "https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration" | \ + jq -r ".token_endpoint") + + export KEYCLOAK_KEYS_ENDPOINT=$(curl -k \ + "https://$KEYCLOAK_IP:8443/realms//.well-known/openid-configuration" | \ + jq -r ".jwks_uri") ``` - Back up the original configuration files: