Kong Manager with OpenID Connect

Uses: Kong Gateway
Related Documentation
Incompatible with
konnect
Related Resources

Kong Gateway provides the ability to bind authentication for Kong Manager admins to an organization’s OpenID Connect identity provider. Set up your identity provider, then configure Kong Gateway using the Kong configuration file or as environment variables.

OpenID Connect authentication for Kong Manager is enabled and configured entirely through kong.conf, and uses the OpenID Connect plugin in the background. You do not need to manually enable the OpenID Connect plugin.

Supported configuration options

Kong Gateway uses the config parameter admin_gui_auth_conf to configure the OIDC plugin. To customize examples in this guide, refer to the OpenID Connect plugin documentation and modify the configuration according to your requirements.

The following parameters can’t be customized. They are controlled internally, and any values provided for them will be ignored:

  • auth_methods
  • login_action
  • login_methods
  • login_tokens
  • logout_methods
  • logout_query_arg
  • logout_revoke_access_token
  • logout_revoke_refresh_token
  • logout_revoke
  • refresh_tokens
  • upstream_access_token_header
  • upstream_id_token_header
  • upstream_user_info_header (while search_user_info is true)

Important: In v3.6.x, many of the parameters under admin_gui_auth_conf changed their behavior. If you had a previous group mapping configuration and upgraded to 3.6 or later, review the changes and adjust your configuration accordingly.

Enable OpenID Connect for Kong Manager

The following examples show you how to enable OIDC auth for Kong Manager.

While authenticating Kong Manager with OpenID Connect, make sure that your IdP supports the authorization_code grant type and is enabled for the associated client.

Review supported configuration options to customize the configuration stored in admin_gui_auth_conf.

Next, to start using OIDC auth, either invite admins manually or set up authenticated group mapping.

When authenticating Kong Manager with OpenID Connect, the session mechanism inside the plugin is used to persist the authorization state. Refer to the documentation for parameters prefixed by [config.session_*](/plugins/openid-connect/reference/#schema--config-session-absolute-timeout) to learn more.

Recommendations to enhance session security

For enhanced security, we recommend setting a few session parameters:

  • session_secret: A randomly generated secret will be used if unspecified.
  • session_cookie_secure: Defaults to false. We recommend setting this value to true when using HTTPS.
  • session_cookie_same_site: Consider upgrading this value to Strict when using the same domain for the Admin API and Kong Manager.

OIDC authenticated group mapping

Using Kong’s OpenID Connect plugin (OIDC), you can map identity provider (IdP) groups to Kong roles.

With IdP group mapping, admin accounts are created automatically. Adding a user to Kong in this way gives them access to Kong Manager based on their group in the IdP. The mapping removes the task of manually managing access in Kong Gateway, because it makes the IdP the system of record.

Roles assigned to admins are also managed by the IdP. 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 to Kong Manager. Don’t assign or unassign admin roles in Kong Gateway manually, as any changes will be overwritten by the IdP during the next login.

Important: In v3.6.x, many of the parameters under admin_gui_auth_conf changed their behavior. If you had a previous group mapping configuration and upgraded to 3.6 or later, review the changes and adjust your configuration accordingly.

Review important values

In the following examples, you specify the admin_claim and authenticated_groups_claim parameters to identify which admin value and role name to map from the IdP to Kong Gateway, as well as the admin_auto_create_rbac_token_disabled to specify whether an RBAC token is created for admins in Kong.

Parameter

Description

admin_claim This value specifies which IdP username value should map to Kong Manager. The username and password are required for the user to log into the IdP.
authenticated_groups_claim This value specifies which IdP claim should be used to assign Kong Gateway roles to the specified Kong Gateway admin. The value depends on your IdP: for example, Okta configures claims for groups, and another IdP might configure them as roles.

In the IdP, the group claim value must follow the format WORKSPACE_NAME:ROLE_NAME.

For example, if "authenticated_groups_claim": ["groups"] is specified, and in the IdP groups:["default:super-admin"] is specified, the administrators specified in admin_claim are assigned to the super-admin role in the default Kong Gateway workspace.

If the mapping doesn’t work as expected, decode the JWT that’s created by your IdP, and make sure that the admin ID token includes the key:value pair groups:["default:super-admin"] for the case of this example, or the appropriate claim name and claim value as set in your IdP.
admin_auto_create_rbac_token_disabled This is a boolean value that enables or disables RBAC token creation when automatically creating admins with OpenID Connect. The default is false.

  • Set to true to disable automatic token creation for admins
  • Set to false to enable automatic token creation for admins
admin_auto_create This is a value boolean value that enables or disables admin auto-creation with OpenID Connect. The default is true.

  • Set to true to enable automatic admin creation
  • Set to false to disable automatic admin creation

Set up authenticated group mapping

The following examples show you how to set up OpenID Connect authenticated group mapping for Kong Manager.

Review supported configuration options to customize the configuration stored in admin_gui_auth_conf.

Migrate OIDC configuration from older versions v3.6+

As of Gateway v3.6, Kong Manager uses the session management mechanism in the OpenID Connect plugin. admin_gui_session_conf is no longer required when authenticating with OIDC. Instead, session-related configuration parameters are set in admin_gui_auth_conf (like session_secret).

We recommend reviewing your configuration, as some session-related parameters in admin_gui_auth_conf have different default values compared to the ones in admin_gui_session_conf.

admin_gui_auth_conf

See the following summary of changes to attributes of admin_gui_auth_conf, and follow the individual links for further information:

Parameter

Old behavior

New behavior

scopes Old default: ["openid", "profile", "email"] New default: ["openid", "email", "offline_access"]
admin_claim Required Optional (Default: "email")
authenticated_groups_claim Required Optional (Default: ["groups"])
redirect_uri Takes an array of URLs pointing to Kong Manager Takes an array of URLs pointing to the Admin API’s /auth endpoint
login_redirect_uri Optional Required
logout_redirect_uri Optional Required

scopes

While using the OpenID Connect plugin with Kong Manager, scopes now have a default value of ["openid", "email", "offline_access"] if not specified.

  • openid: Essential for OpenID Connect.
  • email: Retrieves the user’s email address and includes it in the ID token.
  • offline_access: Essential refresh tokens to refresh the access tokens and sessions.

This parameter can be modified according to your needs. However, "openid" and "offline_access" should always be included to ensure the OpenID Connect plugin works normally. Also, make sure that scopes contains sufficient scopes for the claim specified by this parameter (for example, "email" in the default scopes).

admin_claim

admin_claim is now an optional parameter. If not set, it defaults to "email".

This parameter is used while looking up the admin’s username from the ID token. When configuring this setting, make sure that scopes contains sufficient scopes for the claim specified by this parameter.

authenticated_groups_claim

authenticated_groups_claim is now an optional parameter. If not set, it defaults to ["groups"].

This parameter is used while looking up the admin’s associated groups from the ID token.

redirect_uri

redirect_uri now should be configured as an array of URLs that points to Admin API’s authentication endpoint <ADMIN_API>/auth (for example,["http://localhost:8001/auth"]). Previously, redirect_uri was a list of URLs pointing to Kong Manager (for example,["http://localhost:8002"]).

Users are recommended to update the client/application settings in their IdP to ensure that <ADMIN_API>/auth (for example,http://localhost:8001/auth) is in the allow list for redirect URIs.

login_redirect_uri

login_redirect_uri is now a required parameter to configure the destination after authenticating with the IdP. It should be always be an array of URLs that points to the Kong Manager (for example, ["http://localhost:8002"]).

logout_redirect_uri

logout_redirect_uri is now a required parameter to configure the destination after logging out from the IdP. It should be always be an array of URLs that points to the Kong Manager (for example, ["http://localhost:8002"]).

Previously, Kong Manager didn’t perform an RP-initiated logout from the IdP when a user request to logout. From Gateway v3.6 and onwards, Kong Manager will perform an RP-initiated logout upon user logout.

admin_gui_session_conf

As the OpenID Connect plugin now has a built-in session management mechanism, admin_gui_session_conf is no longer used while authenticating with OIDC. You should also update your configuration if you have previously configured session management via admin_gui_session_conf for OIDC.

Additionally, the default values of some parameters have been changed. See the following for more details:

Old parameter name and location

New parameter name and location

Old default

New default

admin_gui_session_conf.secret admin_gui_auth_conf.session_secret
admin_gui_session_conf.cookie_secure admin_gui_auth_conf.session_cookie_secure true false
admin_gui_session_conf.cookie_samesite admin_gui_auth_conf.session_cookie_same_site Strict Lax

secret

You should now configure this via admin_gui_auth_conf.session_secret.

If not set, Kong Gateway will randomly generate a secret.

You should now configure this via admin_gui_auth_conf.session_cookie_secure.

Previously, cookie_secure was set to true if not specified. However, admin_gui_auth_conf.session_cookie_secure now has a default value of false. If you are using HTTPS rather than HTTP, we recommend enabling this option to enhance security.

You should now configure this via admin_gui_auth_conf.session_cookie_same_site.

Previously, cookie_samesite was set to Strict if not specified. However, admin_gui_auth_conf.session_cookie_same_site now has a default value of Lax. If you are using the same domain for the Admin API and Kong Manager,

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!