Skip to content
|
Kong Gateway
3.9.x (latest)
github-edit-pageEdit this page
report-issueReport an issue

Migrate from Previous Configurations

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

The following parameters are not required and controlled internally, and the provided values 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)

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, we recommend upgrading this setting to Strict to enhance security.

Learn more about SameSite in the Cookie.