我的书签
添加书签
移除书签You are browsing documentation for an older version. See the latest documentation here.
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_methodslogin_actionlogin_methodslogin_tokenslogout_methodslogout_query_arglogout_revoke_access_tokenlogout_revoke_refresh_tokenlogout_revokerefresh_tokensupstream_access_token_headerupstream_id_token_headerupstream_user_info_header(whilesearch_user_infoistrue)
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.
cookie_secure
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.
cookie_samesite
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.
