From d5d847524e381e8880cc70a779e3f99c489a2212 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Tue, 11 Nov 2025 15:34:22 +1100 Subject: [PATCH 1/6] Emphasise that OIDC is only for interactive users OpenID Connect is a protocol for authenticating interactive users. However, because identity platforms that support OIDC often support other protocols that can be used for non-interactive users, it is common for readers to end up on the OIDC page looking for ways to authenticate non-interactive users. The docs attempt to correct this misconception by refering to a "web application" but that was easy to miss. This change makes it more explicit that OIDC is not a viable option for service authentication and recommends JWT instead. --- .../users-roles/cluster-or-deployment-auth/openid-connect.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md index fd0c24cd99..e2e4ab363b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -470,6 +470,11 @@ xpack.security.authc.providers: The OpenID Connect realm is designed to allow users to authenticate to {{kib}}. As a result, most sections of this guide assume {{kib}} is used. This section describes how a custom web application could use the relevant OpenID Connect REST APIs to authenticate the users to {{es}} with OpenID Connect. +::::{note} +The OpenID Connect protocol is used to authenticate interactive users via a web browser. It relies on the user being able to open URLs in their browser and, if necessary, enter their credentials into the login page that is displayed. +{{es}} does not support using OpenID Connect to authenticate a non-interactive user (for example, a "service principal"). If you wish to authenticate a service, then the [JWT](jwt.md) realm may be a suitable alternative. +:::: + Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in {{es}} and in principle exchange a SAML or OpenID Connect Authentication response for an {{es}} access token and a refresh token. The access token is used as credentials for subsequent calls to {{es}}. The refresh token enables the user to get new {{es}} access tokens after the current one expires. ::::{note} From 6e570b283cf25e7fccec6942e29601e60794332e Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Tue, 11 Nov 2025 15:40:30 +1100 Subject: [PATCH 2/6] Remove unncessary comma --- .../users-roles/cluster-or-deployment-auth/openid-connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md index e2e4ab363b..820e0c1c74 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -472,7 +472,7 @@ The OpenID Connect realm is designed to allow users to authenticate to {{kib}}. ::::{note} The OpenID Connect protocol is used to authenticate interactive users via a web browser. It relies on the user being able to open URLs in their browser and, if necessary, enter their credentials into the login page that is displayed. -{{es}} does not support using OpenID Connect to authenticate a non-interactive user (for example, a "service principal"). If you wish to authenticate a service, then the [JWT](jwt.md) realm may be a suitable alternative. +{{es}} does not support using OpenID Connect to authenticate a non-interactive user (for example, a "service principal"). If you wish to authenticate a service then the [JWT](jwt.md) realm may be a suitable alternative. :::: Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in {{es}} and in principle exchange a SAML or OpenID Connect Authentication response for an {{es}} access token and a refresh token. The access token is used as credentials for subsequent calls to {{es}}. The refresh token enables the user to get new {{es}} access tokens after the current one expires. From d2f4534f3b8fe25fe76d9674e6ca6fcad00320b0 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Thu, 13 Nov 2025 17:05:32 +1100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Vlada Chirmicci --- .../users-roles/cluster-or-deployment-auth/openid-connect.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md index 820e0c1c74..6eec0b2a50 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -471,8 +471,8 @@ xpack.security.authc.providers: The OpenID Connect realm is designed to allow users to authenticate to {{kib}}. As a result, most sections of this guide assume {{kib}} is used. This section describes how a custom web application could use the relevant OpenID Connect REST APIs to authenticate the users to {{es}} with OpenID Connect. ::::{note} -The OpenID Connect protocol is used to authenticate interactive users via a web browser. It relies on the user being able to open URLs in their browser and, if necessary, enter their credentials into the login page that is displayed. -{{es}} does not support using OpenID Connect to authenticate a non-interactive user (for example, a "service principal"). If you wish to authenticate a service then the [JWT](jwt.md) realm may be a suitable alternative. +The OpenID Connect protocol enables authentication for interactive users via a web browser. Users must be able to open a login URL in their browser and enter credentials when prompted. +{{es}} does not support using OpenID Connect to authenticate non-interactive users such as service principals or automated processes. If you wish to authenticate a service, the [JWT](jwt.md) realm may be a suitable alternative. :::: Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in {{es}} and in principle exchange a SAML or OpenID Connect Authentication response for an {{es}} access token and a refresh token. The access token is used as credentials for subsequent calls to {{es}}. The refresh token enables the user to get new {{es}} access tokens after the current one expires. From 235911c9e7e7c780b51c5a3436c95b28c5618d0e Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Fri, 28 Nov 2025 18:14:47 +1100 Subject: [PATCH 4/6] Add more explanation --- .../users-roles/cluster-or-deployment-auth/openid-connect.md | 1 + 1 file changed, 1 insertion(+) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md index 6eec0b2a50..d7a28c8519 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -473,6 +473,7 @@ The OpenID Connect realm is designed to allow users to authenticate to {{kib}}. ::::{note} The OpenID Connect protocol enables authentication for interactive users via a web browser. Users must be able to open a login URL in their browser and enter credentials when prompted. {{es}} does not support using OpenID Connect to authenticate non-interactive users such as service principals or automated processes. If you wish to authenticate a service, the [JWT](jwt.md) realm may be a suitable alternative. +The JWT realm is able to authenticate the sorts of tokens that are produced by OpenID Connect providers. :::: Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in {{es}} and in principle exchange a SAML or OpenID Connect Authentication response for an {{es}} access token and a refresh token. The access token is used as credentials for subsequent calls to {{es}}. The refresh token enables the user to get new {{es}} access tokens after the current one expires. From 7d9babcd503df971c47298d5d3ceabcd80876669 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Fri, 28 Nov 2025 18:39:11 +1100 Subject: [PATCH 5/6] Improve wording --- .../users-roles/cluster-or-deployment-auth/openid-connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md index d7a28c8519..bc9f9ad32d 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -473,7 +473,7 @@ The OpenID Connect realm is designed to allow users to authenticate to {{kib}}. ::::{note} The OpenID Connect protocol enables authentication for interactive users via a web browser. Users must be able to open a login URL in their browser and enter credentials when prompted. {{es}} does not support using OpenID Connect to authenticate non-interactive users such as service principals or automated processes. If you wish to authenticate a service, the [JWT](jwt.md) realm may be a suitable alternative. -The JWT realm is able to authenticate the sorts of tokens that are produced by OpenID Connect providers. +The JWT realm is able to authenticate the tokens that are produced by OpenID Connect providers. :::: Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in {{es}} and in principle exchange a SAML or OpenID Connect Authentication response for an {{es}} access token and a refresh token. The access token is used as credentials for subsequent calls to {{es}}. The refresh token enables the user to get new {{es}} access tokens after the current one expires. From 7fd46b99b343261e6a38ac32f93b4260d0994337 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Fri, 28 Nov 2025 18:49:00 +1100 Subject: [PATCH 6/6] Improve wording (again) --- .../users-roles/cluster-or-deployment-auth/openid-connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md index bc9f9ad32d..5645df26ec 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -473,7 +473,7 @@ The OpenID Connect realm is designed to allow users to authenticate to {{kib}}. ::::{note} The OpenID Connect protocol enables authentication for interactive users via a web browser. Users must be able to open a login URL in their browser and enter credentials when prompted. {{es}} does not support using OpenID Connect to authenticate non-interactive users such as service principals or automated processes. If you wish to authenticate a service, the [JWT](jwt.md) realm may be a suitable alternative. -The JWT realm is able to authenticate the tokens that are produced by OpenID Connect providers. +The JWT realm is able to authenticate tokens that are produced by OpenID Connect providers. :::: Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in {{es}} and in principle exchange a SAML or OpenID Connect Authentication response for an {{es}} access token and a refresh token. The access token is used as credentials for subsequent calls to {{es}}. The refresh token enables the user to get new {{es}} access tokens after the current one expires.