OIDC Authenticated Group Mapping

Using Kong’s OpenID Connect plugin (OIDC), you can map identity provider (IdP) groups to Kong roles. Adding a user to Kong in this way gives them access to Kong based on their group in the IdP.

After starting Kong Gateway with the desired configuration, you can create new admins whose usernames match those in your IdP. Those users will then be able to accept invitations to join Kong Manager and log in with their IdP credentials.

If an admin’s group changes in the IdP, their Kong admin account’s associated role also changes in Kong Gateway the next time they log in through Kong Manager. The mapping removes the task of manually managing access in Kong Gateway, as it makes the IdP the system of record.

Here’s how OIDC authenticaticated group mapping works:

  1. Create roles in Kong Gateway using either the Kong Admin API or Kong Manager.
  2. Create groups and associate roles with the groups.
  3. Configure the OIDC plugin to connect with your IdP.
  4. When users log in to Kong Manager, they get permissions based on the IdP group(s) they belong to.

Prerequisites

Create Kong Groups and Assign Roles

Note: The following examples assume that you have RBAC enabled with Basic Auth and are transitioning to OpenID Connect.

Kong Manager

Kong Admin API

Create a group and assign a role to it:

  1. Open Teams from the top navigation.
  2. Click the Groups tab.
  3. Click Create New Group.

  4. Set the Group Name to match your IdP group.

    Note: Group names are case-sensitive. Make sure to match your IdP group name exactly.

  5. (Optional) In the Comment field, enter a description for the group.

  6. Click on Add/Edit Roles, then choose a workspace and a role.
  7. Save the role assignment, then click Create.

Create an admin for the group:

  1. Open the Teams from the top navigation.
  2. Click the Admins tab.
  3. Click Invite Admin.

  4. Enter a username and email, and optionally a custom ID to make the admin easy for you to identify.

    Note: Make sure the username exactly matches the admin’s name in your IdP.

  5. Ensure the Enable RBAC token checkbox is checked.

  6. Save the role assignment, then click Invite Admin.

  7. Create a group, making sure the group name parameter matches your IdP group name:

    1.  $ curl -X POST --url http://<admin-hostname>:8001/groups \
    2.    --header 'content-type: application/json' \
    3.    --header 'kong-admin-token: <yourtoken>' \
    4.    --data '{
    5.        "comment": "example group",      
    6.        "name": "examplegroup"      
    7.      }'

    Note: Group names are case-sensitive. Make sure to match your IdP group name exactly.

  8. Assign a role to the group:

    1.  $ curl -X POST --url http://<admin-hostname>:8001/groups/{group-id}/roles \
    2.    --header 'content-type: application/json' \
    3.    --header 'kong-admin-token: <yourtoken>' \
    4.    --data '{   
    5.        "rbac_role_id": "e948171e-699c-4035-9b74-2b2b576d9644",
    6.          "workspace_id": "236bfa99-cf09-4389-afa8-e2bd6da89fd3"
    7.      }'

    Where:

  9. Create an admin for the group:

    1.  $ curl -X POST --url http://<admin-hostname>:8001/admins \
    2.    --header 'content-type: application/json' \
    3.    --header 'kong-admin-token: <yourtoken>' \
    4.    --data '{
    5.    "username": "<someusername>",
    6.    "custom_id": "<examplename>",
    7.    "email": "<your-email@company.com>",
    8.    "rbac_token_enabled": true
    9.  }'

Notice how in the instructions above, you did not assign a role to your admin. The role will be matched with the role assigned to them in the IdP.

Apply OIDC Auth Mapping to Kong Gateway

Kubernetes with Helm

Docker

kong.conf

  1. Create a configuration file for the OIDC plugin and save it as admin_gui_auth_conf. For group mapping, you must include the authenticated_groups_claim parameter as part of this configuration.

    For example, the configuration should look something like this:

    1.  {
    2.    "issuer": "<https://my-auth-url>",
    3.    "client_id": ["<someid>"],
    4.    "client_secret": ["<somesecret>"],
    5.    "consumer_by": ["username","custom_id"],
    6.    "ssl_verify": false,
    7.    "consumer_claim": ["sub"],
    8.    "leeway": 60,
    9.    "redirect_uri": ["<http://manager.admin-hostname.com>"],
    10.    "login_redirect_uri": ["<http://manager.admin-hostname.com>"],
    11.    "logout_methods": ["GET", "DELETE"],
    12.    "logout_query_arg": "logout",
    13.    "logout_redirect_uri": ["<http://manager.admin-hostname.com>"],
    14.    "scopes": ["openid","profile","email","offline_access"],
    15.    "authenticated_groups_claim": ["groups"],
    16.    "auth_methods": ["authorization_code"]
    17.  }

    For detailed descriptions of all the parameters used here, and many other customization options, see the OpenID Connect parameter reference.

  2. Create a secret from the file you just created:

    1.  $ kubectl create secret generic kong-idp-conf --from-file=admin_gui_auth_conf -n kong

  3. Update the RBAC section of the deployment values.yml file with the following parameters:

    1.  rbac:
    2.    enabled: true
    3.    admin_gui_auth: openid-connect
    4.    session_conf_secret: kong-session-conf   
    5.    admin_gui_auth_conf_secret: kong-idp-conf

  4. Using Helm, upgrade the deployment with your YAML filename:

    1.  $ helm upgrade --install kong-ee kong/kong -f ./myvalues.yaml -n kong

If you have a Docker installation, run the following command to set the needed environment variables and reload the Kong Gateway configuration.

Substitute all variables in angled brackets (< >) with your own values:

  1. $ echo "
  2.   KONG_ENFORCE_RBAC=on \
  3.   KONG_ADMIN_GUI_AUTH=openid-connect \
  4.   KONG_ADMIN_GUI_AUTH_CONF='{
  5.       \"issuer\": \"<https://my-auth-url>\",
  6.       \"client_id\": [\"<someid>\"],
  7.       \"client_secret\": [\"<somesecret>\"],
  8.       \"consumer_by\": [\"username\",\"custom_id\"],
  9.       \"ssl_verify\": false,
  10.       \"consumer_claim\": [\"sub\"],
  11.       \"leeway\": 60,
  12.       \"redirect_uri\": [\"<http://manager.admin-hostname.com>\"],
  13.       \"login_redirect_uri\": [\"<http://manager.admin-hostname.com>\"],
  14.       \"logout_methods\": [\"GET\", \"DELETE\"],
  15.       \"logout_query_arg\": \"logout\",
  16.       \"logout_redirect_uri\": [\"<http://manager.admin-hostname.com>\"],
  17.       \"scopes\": [\"openid\",\"profile\",\"email\",\"offline_access\"],
  18.       \"authenticated_groups_claim\": [\"groups\"],
  19.       \"auth_methods\": [\"authorization_code\"]
  20.     }' kong reload exit" | docker exec -i <kong-container-id> /bin/sh

Replace <kong-container-id> with the ID of your container.

  1. Navigate to your kong.conf file.

  2. With RBAC enabled, add the admin_gui_auth and admin_gui_auth_conf properties to the file:

    1.  enforce_rbac = on
    2.  admin_gui_auth = openid-connect
    3.  admin_gui_auth_conf = {
    4.      "issuer": "<https://my-auth-url>",
    5.      "client_id": ["<someid>"],
    6.      "client_secret": ["<somesecret>"],
    7.      "consumer_by": ["username","custom_id"],
    8.      "ssl_verify": false,
    9.      "consumer_claim": ["sub"],
    10.      "leeway": 60,
    11.      "redirect_uri": ["<http://manager.admin-hostname.com>"],
    12.      "login_redirect_uri": ["<http://manager.admin-hostname.com>"],
    13.      "logout_methods": ["GET", "DELETE"],
    14.      "logout_query_arg": "logout",
    15.      "logout_redirect_uri": ["<http://manager.admin-hostname.com>"],
    16.      "scopes": ["openid","profile","email","offline_access"],
    17.      "authenticated_groups_claim": ["groups"],
    18.      "auth_methods": ["authorization_code"]
    19.    }

    For detailed descriptions of all the parameters used here, and many other customization options, see the OpenID Connect parameter reference.

  3. Restart Kong Gateway to apply the file.

    1.  $ kong restart -c /path/to/kong.conf