OpenID Connect Quick Start
You can use the OpenID Connect (OIDC) protocol to authenticate users in Kibana using external Identity Providers (IdP).
This chapter describes the basic setup of OIDC with Search Guard. This will work in most cases. However, some setups require special configurations for TLS, proxies, or similar things. Please refer to the section Advanced Configuration for this.
To use OIDC, you need to have an Identity Provider (IdP) supporting OIDC. Furthermore, HTTPS must be configured for Kibana.
First, create a new client representing your Kibana installation in your Identity Provider. The exact procedure for this is specific to the IdP. When configuring the client, you must make sure that the following settings are configured like this:
- Root URL: The base URL of the Kibana instance. For example,
Valid Redirect URLs: The base URL of Kibana plus a
*wildcard for paths. For example,
Also, you need to make sure that the roles of a user are mapped to a JWT claim.
- All users who are supposed to log in to Kibana must have certain privileges. If you use the default
sg_roles_mapping.ymlconfiguration, just make sure that the IdP assigns the role
kibanauserto the users who shall be able to log in. The default
sg_roles_mapping.ymlthen maps this to the Search Guard role
SGS_KIBANA_USER. If you are not using the default
sg_roles_mappingyou need to make sure that it maps
SGS_KIBANA_USERto a suitable backend role provided by the IdP.
You need to keep a couple of values from the IdP setup ready for the next step. These values are:
- The client id
- The client secret
- The name of the OIDC ID token claim to which you mapped the roles
- The URL of the OIDC configuration endpoint. This URL generally looks like this:
Search Guard Setup
Now you need to edit the
The default version of this file contains an entry for password-based authentication:
default: auth_domains: - type: basic
If you don’t want to use password-based authentication, replace the entry
- type: basic by the new configuration. If you want to continue to use password-based authentication besides OIDC, just add the new configuration below. The following examples assume that you have removed the password-based authentication.
sg_frontend_authc.yml configuration for OIDC looks like this:
default: auth_domains: - type: oidc oidc.client_id: "my-kibana-client" oidc.client_secret: "client-secret-from-idp" oidc.idp.openid_configuration_url: "https://your.idp/.../.well-known/openid-configuration" user_mapping.roles.from_comma_separated_string: "oidc_id_token.roles"
You need to replace the values for
idp.openid_configuration_url by the values configured in the IdP. In the
user_mapping.roles config option, specify a JSON path expression to access the roles inside the OIDC ID token retrieved from the IdP. The attribute
oidc_id_token is initialized with the claims retrieved from the ID token.
To use OIDC with Kibana it is necessary to configure the external URL of Kibana in the file
config/kibana.yml in your Kibana installation.
For Kibana 7.11 and newer versions, you can use the built-in setting
For older versions of Kibana, please use the setting
Furthermore, the OIDC protocol requires specific settings for the cookies used by Search Guard (For background information on this, see this blog post at auth0.com. To achieve this, add the following settings to
searchguard.cookie.isSameSite: None searchguard.cookie.secure: true
Activate the Setup
To activate the setup, do the following:
- If you edited
kibana.yml, ensure that you restart the Kibana instance.
sgctlto upload the new
sg_frontend_authc.ymlfile to Search Guard.
That’s it. If you navigate in a browser to your Kibana instance, you should be directed to the IdP login page.