From 7d0f0450ffc0109cdb83132606ff20789a163e31 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 16:47:10 +0000 Subject: [PATCH 01/14] Initial plan From 6ac1a1d369f3d5679bb218d6cd682e9b84356578 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 16:49:46 +0000 Subject: [PATCH 02/14] docs: Add OAUTH authentication module documentation Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/a19d1778-aeb6-4397-92cc-be7994b0b059 Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../appendix-auth-modules.adoc | 87 +++++++++++++++++++ .../asciidoc/integrators-guide/chap-auth.adoc | 60 +++++++++++++ 2 files changed, 147 insertions(+) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index f32c400c2..63536d969 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -291,4 +291,91 @@ a|authentication.json |=== In general, if you add a custom property, the Admin UI writes changes to the `authentication.json` or `ui-configuration.json` files. +[#oauth-module-details] +=== OAUTH Module Configuration Options + +The `OAUTH` module authenticates users via a generic OAuth 2.0 provider. It validates an OAuth 2.0 `access_token` by calling the provider's `userinfo_endpoint`. Two HTTP headers are required: one carrying the token and one naming the provider resolver. For more information, see xref:chap-auth.adoc#oauth-module["OAUTH"]. + +[#table-oauth-module-prop] +.OAUTH Module Properties +[cols="28%,29%,43%"] +|=== +|Authentication Property |Property as Listed in the Admin UI |Description + +a|`enabled` +a|Module Enabled +a|Whether OpenIDM uses the module. + +a|`authTokenHeader` +a|OAuth Token Header +a|Name of the HTTP request header that carries the OAuth 2.0 access token. This header is required; authentication fails if it is absent. + +a|`authResolverHeader` +a|OAuth Resolver Header +a|Name of the HTTP request header that identifies the provider resolver to use. The value must match the `name` of an entry in the `resolvers` array. This header is required. + +a|`queryOnResource` +a|Query on Resource +a|Managed object endpoint to query after the token is validated against the provider (for example, `managed/oauth`). + +a|`propertyMapping.authenticationId` +a|Authentication ID +a|Attribute in the managed object used as the user identifier. + +a|`propertyMapping.userRoles` +a|User Roles +a|Attribute in the managed object used for authorization roles (for example, `authzRoles`). + +a|`defaultUserRoles` +a|Default User Roles +a|Roles assigned to all users who authenticate successfully through this module. + +a|`augmentSecurityContext` +a|Augment Security Context +a|Optional script executed after a successful authentication request. +|=== + +[#table-oauth-resolver-prop] +.OAUTH Resolver Properties (within `resolvers[]`) +[cols="30%,70%"] +|=== +|Property |Description + +a|`name` +a|Unique resolver name. The value sent in the `authResolverHeader` HTTP header must match this name. + +a|`type` +a|Always `OAUTH`. + +a|`client_id` +a|OAuth 2.0 client ID registered with the provider. + +a|`client_secret` +a|OAuth 2.0 client secret registered with the provider. + +a|`authorization_endpoint` +a|Provider's authorization endpoint URL. + +a|`token_endpoint` +a|Provider's token endpoint URL. + +a|`userinfo_endpoint` +a|Provider's userinfo endpoint URL. The access token is validated by calling this endpoint. + +a|`scope` +a|List of OAuth 2.0 scopes to request (for example, `["openid", "profile", "email"]`). + +a|`authenticationId` +a|Attribute from the userinfo endpoint response used as the user identifier (for example, `_id` or `sub`). + +a|`propertyMap` +a|Array of `{source, target}` pairs that map attributes from the provider's userinfo response to attributes on the managed object. + +a|`icon` +a|HTML markup for the social login button displayed in the UI. + +a|`enabled` +a|Whether this resolver is active. +|=== + diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index 80ce42f3b..46b7ddece 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -480,6 +480,66 @@ Set up logins with OpenAM, to work with the related login session cookie, known IWA:: The IWA module enables users to authenticate by using Integrated Windows Authentication (IWA), rather than by providing a username and password. For information about configuring the IWA module with OpenIDM, see xref:#openidm-auth-kerberos["Configuring IWA Authentication"]. +[#oauth-module] +OAUTH:: +The `OAUTH` module authenticates users via a generic OAuth 2.0 provider by validating an OAuth 2.0 `access_token` against the provider's `userinfo_endpoint`. Unlike the `OPENID_CONNECT` module, it does not use JWT identity tokens. ++ +The module requires two HTTP request headers: ++ +* `authTokenHeader` — carries the OAuth 2.0 access token. +* `authResolverHeader` — names the provider resolver (from the `resolvers` list) that should validate the token. ++ +Using two headers allows a single module instance to support multiple OAuth providers simultaneously, each defined as a separate entry in the `resolvers` array. ++ +The following sample configuration shows the `OAUTH` module with a single provider resolver: ++ +[source, json] +---- +{ + "name" : "OAUTH", + "enabled" : true, + "properties" : { + "augmentSecurityContext": { + "type" : "text/javascript", + "file" : "auth/populateAsManagedUserFromRelationship.js" + }, + "propertyMapping" : { + "userRoles" : "authzRoles", + "authenticationId" : "_id" + }, + "defaultUserRoles" : [ + "openidm-authorized" + ], + "resolvers" : [ + { + "name" : "myProvider", + "type" : "OAUTH", + "icon" : "", + "scope" : ["profile", "email"], + "authenticationId" : "_id", + "propertyMap" : [ + { + "source" : "sub", + "target" : "userName" + } + ], + "enabled" : true, + "client_id" : "your-client-id", + "client_secret" : "your-client-secret", + "authorization_endpoint" : "https://provider.example.com/oauth2/authorize", + "token_endpoint" : "https://provider.example.com/oauth2/access_token", + "userinfo_endpoint" : "https://provider.example.com/oauth2/userinfo" + } + ], + "queryOnResource" : "managed/oauth", + "authTokenHeader" : "authToken", + "authResolverHeader" : "provider" + } +} +---- ++ +For detailed property descriptions, see xref:appendix-auth-modules.adoc#oauth-module-details["OAUTH Module Configuration Options"]. + -- From 51db01d0e8cb20d73fcda69b6cb98011cfc0f532 Mon Sep 17 00:00:00 2001 From: Valery Kharseko Date: Thu, 26 Mar 2026 19:59:12 +0300 Subject: [PATCH 03/14] Update openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc In this section, the bullets read as if the literal HTTP header names are authTokenHeader and authResolverHeader, but those are configuration property keys. The actual request header names are whatever values you configure for those properties (for example, authToken and provider in the sample). Please reword to avoid readers sending the wrong header names. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../src/main/asciidoc/integrators-guide/chap-auth.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index 46b7ddece..1de8f6062 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -484,10 +484,10 @@ The IWA module enables users to authenticate by using Integrated Windows Authent OAUTH:: The `OAUTH` module authenticates users via a generic OAuth 2.0 provider by validating an OAuth 2.0 `access_token` against the provider's `userinfo_endpoint`. Unlike the `OPENID_CONNECT` module, it does not use JWT identity tokens. + -The module requires two HTTP request headers: +The module requires two HTTP request headers. Their names are configured by the following properties: + -* `authTokenHeader` — carries the OAuth 2.0 access token. -* `authResolverHeader` — names the provider resolver (from the `resolvers` list) that should validate the token. +* `authTokenHeader` — configuration property that specifies the name of the HTTP header carrying the OAuth 2.0 access token (for example, `authToken` in the sample below). +* `authResolverHeader` — configuration property that specifies the name of the HTTP header that identifies the provider resolver (from the `resolvers` list) that should validate the token (for example, `provider` in the sample below). + Using two headers allows a single module instance to support multiple OAuth providers simultaneously, each defined as a separate entry in the `resolvers` array. + From 97c35814b0e2b7b8ba4f8a9294ed48c717a24980 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 17:01:04 +0000 Subject: [PATCH 04/14] docs: Fix inconsistent authenticationId in OAUTH sample config Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/df28ebe1-6881-42be-b79b-77ab0f6b12de Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index 1de8f6062..4a06e0cef 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -516,7 +516,7 @@ The following sample configuration shows the `OAUTH` module with a single provid "type" : "OAUTH", "icon" : "", "scope" : ["profile", "email"], - "authenticationId" : "_id", + "authenticationId" : "sub", "propertyMap" : [ { "source" : "sub", From 93cfe4a001c5cd6b7dad89965bcd82cbcc361556 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 17:09:34 +0000 Subject: [PATCH 05/14] docs: Add resolvers row to OAUTH module properties table Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/667da02d-128a-4a9a-b9e6-043cd4d9a26a Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../asciidoc/integrators-guide/appendix-auth-modules.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index 63536d969..c3168e36e 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -314,6 +314,10 @@ a|`authResolverHeader` a|OAuth Resolver Header a|Name of the HTTP request header that identifies the provider resolver to use. The value must match the `name` of an entry in the `resolvers` array. This header is required. +a|`resolvers` +a|Resolvers +a|Required. Array of provider resolver objects. Each entry configures one OAuth 2.0 provider. At least one entry must be present; see xref:#table-oauth-resolver-prop[OAUTH Resolver Properties] for the properties of each resolver. + a|`queryOnResource` a|Query on Resource a|Managed object endpoint to query after the token is validated against the provider (for example, `managed/oauth`). From 0950d37535ab32a95fcb2ac76f7454642de9bf9b Mon Sep 17 00:00:00 2001 From: Valery Kharseko Date: Thu, 26 Mar 2026 20:20:17 +0300 Subject: [PATCH 06/14] Update openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index 4a06e0cef..fee3fdf87 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -505,7 +505,7 @@ The following sample configuration shows the `OAUTH` module with a single provid }, "propertyMapping" : { "userRoles" : "authzRoles", - "authenticationId" : "_id" + "authenticationId" : "userName" }, "defaultUserRoles" : [ "openidm-authorized" From 26434015c6b0714d7417850e2be019c796f5dcb7 Mon Sep 17 00:00:00 2001 From: Valery Kharseko Date: Thu, 26 Mar 2026 20:21:47 +0300 Subject: [PATCH 07/14] Update openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../main/asciidoc/integrators-guide/appendix-auth-modules.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index c3168e36e..43f297c11 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -370,7 +370,7 @@ a|`scope` a|List of OAuth 2.0 scopes to request (for example, `["openid", "profile", "email"]`). a|`authenticationId` -a|Attribute from the userinfo endpoint response used as the user identifier (for example, `_id` or `sub`). +a|Attribute name in the provider's userinfo endpoint response that contains the user identifier (for example, `_id` or `sub`); this value is mapped to the managed user's `authenticationId` attribute. a|`propertyMap` a|Array of `{source, target}` pairs that map attributes from the provider's userinfo response to attributes on the managed object. From 80818d214370543facce1af61974c9b0aa4c3950 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 17:38:22 +0000 Subject: [PATCH 08/14] docs: Clarify authenticationId distinction in OAUTH sample config Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/020b25db-106b-4ed4-8c2e-8c7809073fcd Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index fee3fdf87..c3ba12a46 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -538,6 +538,8 @@ The following sample configuration shows the `OAUTH` module with a single provid } ---- + +Note that `authenticationId` appears at two different levels with different meanings: inside each `resolvers[]` entry it names the field in the provider's userinfo response that identifies the user (for example, `sub`); at the `propertyMapping` level it names the attribute in the managed object (for example, `userName`) that OpenIDM uses as the authentication identifier after the userinfo fields have been mapped via `propertyMap`. ++ For detailed property descriptions, see xref:appendix-auth-modules.adoc#oauth-module-details["OAUTH Module Configuration Options"]. -- From 67d1349825b959e71e8b08b8390567362ccdb563 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 18:05:18 +0000 Subject: [PATCH 09/14] docs: Clarify authenticationId distinction in appendix module-level table Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/689cd003-ea32-4297-8f02-59e8c1f43803 Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../main/asciidoc/integrators-guide/appendix-auth-modules.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index 43f297c11..3d838b245 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -324,7 +324,7 @@ a|Managed object endpoint to query after the token is validated against the prov a|`propertyMapping.authenticationId` a|Authentication ID -a|Attribute in the managed object used as the user identifier. +a|Attribute name in the managed object (for example, `userName`) that OpenIDM uses as the authentication identifier when querying `queryOnResource`. This is distinct from the resolver-level `authenticationId`, which names the field in the provider's userinfo endpoint response. a|`propertyMapping.userRoles` a|User Roles From bab62db823a3c5044d474018da1743b54f518b36 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 19:11:57 +0000 Subject: [PATCH 10/14] docs: Fix scope example and expand authenticationId note per review Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/64a8adc3-88d4-4b3f-8957-d2933146bd21 Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../main/asciidoc/integrators-guide/appendix-auth-modules.adoc | 2 +- openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index 3d838b245..b2fcf6747 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -367,7 +367,7 @@ a|`userinfo_endpoint` a|Provider's userinfo endpoint URL. The access token is validated by calling this endpoint. a|`scope` -a|List of OAuth 2.0 scopes to request (for example, `["openid", "profile", "email"]`). +a|List of OAuth 2.0 scopes to request (for example, `["profile", "email"]`). a|`authenticationId` a|Attribute name in the provider's userinfo endpoint response that contains the user identifier (for example, `_id` or `sub`); this value is mapped to the managed user's `authenticationId` attribute. diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index c3ba12a46..df6ac8fa9 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -538,7 +538,7 @@ The following sample configuration shows the `OAUTH` module with a single provid } ---- + -Note that `authenticationId` appears at two different levels with different meanings: inside each `resolvers[]` entry it names the field in the provider's userinfo response that identifies the user (for example, `sub`); at the `propertyMapping` level it names the attribute in the managed object (for example, `userName`) that OpenIDM uses as the authentication identifier after the userinfo fields have been mapped via `propertyMap`. +Note that `authenticationId` appears at two different levels with different meanings: inside each `resolvers[]` entry it names the field in the provider's userinfo response that identifies the user (for example, `sub`); at the `propertyMapping` level it names the attribute in the managed object (for example, `userName`) that OpenIDM uses as the authentication identifier after the userinfo fields have been mapped via `propertyMap`. The resolver-level `authenticationId` userinfo field must therefore be included in `propertyMap` and mapped into the managed-object attribute referenced by `propertyMapping.authenticationId`, so that OpenIDM can correlate the resolved user to the `queryOnResource` entry. + For detailed property descriptions, see xref:appendix-auth-modules.adoc#oauth-module-details["OAUTH Module Configuration Options"]. From b9c62c4b674d4e30f5ba9294fcc4a3ad68b796d3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 09:00:46 +0000 Subject: [PATCH 11/14] docs: Restructure OAUTH tables to match OPENAM_SESSION 4-column format Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/c44165d3-6a21-4506-a259-1433cc944981 Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../appendix-auth-modules.adoc | 123 +++++++++++------- 1 file changed, 78 insertions(+), 45 deletions(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index b2fcf6747..f8e5d1d0d 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -298,88 +298,121 @@ The `OAUTH` module authenticates users via a generic OAuth 2.0 provider. It vali [#table-oauth-module-prop] .OAUTH Module Properties -[cols="28%,29%,43%"] +[cols="18%,27%,27%,28%"] |=== -|Authentication Property |Property as Listed in the Admin UI |Description +|Admin UI Label |Default |Description |Configuration File -a|`enabled` a|Module Enabled +a|false a|Whether OpenIDM uses the module. +a|authentication.json -a|`authTokenHeader` a|OAuth Token Header -a|Name of the HTTP request header that carries the OAuth 2.0 access token. This header is required; authentication fails if it is absent. +a|authToken +a|Name of the HTTP request header that carries the OAuth 2.0 access token (configured via `authTokenHeader`). This header is required; authentication fails if it is absent. +a|authentication.json -a|`authResolverHeader` a|OAuth Resolver Header -a|Name of the HTTP request header that identifies the provider resolver to use. The value must match the `name` of an entry in the `resolvers` array. This header is required. +a|provider +a|Name of the HTTP request header that identifies the provider resolver to use (configured via `authResolverHeader`). The value must match the `name` of an entry in the `resolvers` array. This header is required. +a|authentication.json -a|`resolvers` a|Resolvers -a|Required. Array of provider resolver objects. Each entry configures one OAuth 2.0 provider. At least one entry must be present; see xref:#table-oauth-resolver-prop[OAUTH Resolver Properties] for the properties of each resolver. +a|(none) +a|Required. Array of provider resolver objects (configured via `resolvers`). Each entry configures one OAuth 2.0 provider. At least one entry must be present; see xref:#table-oauth-resolver-prop[OAUTH Resolver Properties] for the properties of each resolver. +a|authentication.json -a|`queryOnResource` a|Query on Resource -a|Managed object endpoint to query after the token is validated against the provider (for example, `managed/oauth`). +a|managed/oauth +a|Managed object endpoint to query after the token is validated against the provider (configured via `queryOnResource`). +a|authentication.json -a|`propertyMapping.authenticationId` a|Authentication ID -a|Attribute name in the managed object (for example, `userName`) that OpenIDM uses as the authentication identifier when querying `queryOnResource`. This is distinct from the resolver-level `authenticationId`, which names the field in the provider's userinfo endpoint response. +a|userName +a|Attribute name in the managed object that OpenIDM uses as the authentication identifier when querying the resource (configured via `propertyMapping.authenticationId`). This is distinct from the resolver-level `authenticationId`, which names the field in the provider's userinfo endpoint response. +a|authentication.json -a|`propertyMapping.userRoles` a|User Roles -a|Attribute in the managed object used for authorization roles (for example, `authzRoles`). +a|authzRoles +a|Attribute in the managed object used for authorization roles (configured via `propertyMapping.userRoles`). +a|authentication.json -a|`defaultUserRoles` a|Default User Roles -a|Roles assigned to all users who authenticate successfully through this module. +a|openidm-authorized +a|Roles assigned to all users who authenticate successfully through this module (configured via `defaultUserRoles`). +a|authentication.json -a|`augmentSecurityContext` a|Augment Security Context -a|Optional script executed after a successful authentication request. +a|(none) +a|Optional script executed after a successful authentication request (configured via `augmentSecurityContext`). +a|authentication.json |=== [#table-oauth-resolver-prop] .OAUTH Resolver Properties (within `resolvers[]`) -[cols="30%,70%"] +[cols="18%,27%,27%,28%"] |=== -|Property |Description +|Admin UI Label |Default |Description |Configuration File -a|`name` -a|Unique resolver name. The value sent in the `authResolverHeader` HTTP header must match this name. +a|Name +a|(user-defined) +a|Unique resolver name (configured via `name`). The value sent in the `authResolverHeader` HTTP header must match this name. +a|authentication.json -a|`type` -a|Always `OAUTH`. +a|Type +a|OAUTH +a|Always `OAUTH` (configured via `type`). +a|authentication.json -a|`client_id` -a|OAuth 2.0 client ID registered with the provider. +a|Client ID +a|(user-defined) +a|OAuth 2.0 client ID registered with the provider (configured via `client_id`). +a|authentication.json -a|`client_secret` -a|OAuth 2.0 client secret registered with the provider. +a|Client Secret +a|(user-defined) +a|OAuth 2.0 client secret registered with the provider (configured via `client_secret`). +a|authentication.json -a|`authorization_endpoint` -a|Provider's authorization endpoint URL. +a|Authorization Endpoint +a|(provider URL) +a|Provider's authorization endpoint URL (configured via `authorization_endpoint`). +a|authentication.json -a|`token_endpoint` -a|Provider's token endpoint URL. +a|Token Endpoint +a|(provider URL) +a|Provider's token endpoint URL (configured via `token_endpoint`). +a|authentication.json -a|`userinfo_endpoint` -a|Provider's userinfo endpoint URL. The access token is validated by calling this endpoint. +a|Userinfo Endpoint +a|(provider URL) +a|Provider's userinfo endpoint URL (configured via `userinfo_endpoint`). The access token is validated by calling this endpoint. +a|authentication.json -a|`scope` -a|List of OAuth 2.0 scopes to request (for example, `["profile", "email"]`). +a|Scope +a|["profile", "email"] +a|List of OAuth 2.0 scopes to request (configured via `scope`). +a|authentication.json -a|`authenticationId` -a|Attribute name in the provider's userinfo endpoint response that contains the user identifier (for example, `_id` or `sub`); this value is mapped to the managed user's `authenticationId` attribute. +a|Authentication ID +a|sub +a|Attribute name in the provider's userinfo endpoint response that contains the user identifier (configured via `authenticationId`; for example, `sub`). This value is mapped to the managed user's authentication identifier. +a|authentication.json -a|`propertyMap` -a|Array of `{source, target}` pairs that map attributes from the provider's userinfo response to attributes on the managed object. +a|Property Map +a|(none) +a|Array of `{source, target}` pairs that map attributes from the provider's userinfo response to attributes on the managed object (configured via `propertyMap`). +a|authentication.json -a|`icon` -a|HTML markup for the social login button displayed in the UI. +a|Icon +a|(none) +a|HTML markup for the social login button displayed in the UI (configured via `icon`). +a|authentication.json -a|`enabled` -a|Whether this resolver is active. +a|Enabled +a|true +a|Whether this resolver is active (configured via `enabled`). +a|authentication.json |=== From d06c60f0cb63728226278c93e5d5ffbccdb6b31b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 09:19:52 +0000 Subject: [PATCH 12/14] docs: Restructure OAUTH tables to match OPENAM_SESSION Basic/Advanced format Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/d1a2ac56-e34a-49ab-93f9-fb11f7851b0e Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../appendix-auth-modules.adoc | 139 ++++++++---------- 1 file changed, 63 insertions(+), 76 deletions(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index f8e5d1d0d..d1f3ee717 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -294,124 +294,111 @@ In general, if you add a custom property, the Admin UI writes changes to the `au [#oauth-module-details] === OAUTH Module Configuration Options -The `OAUTH` module authenticates users via a generic OAuth 2.0 provider. It validates an OAuth 2.0 `access_token` by calling the provider's `userinfo_endpoint`. Two HTTP headers are required: one carrying the token and one naming the provider resolver. For more information, see xref:chap-auth.adoc#oauth-module["OAUTH"]. +The `OAUTH` module authenticates users via a generic OAuth 2.0 provider. It validates an OAuth 2.0 `access_token` by calling the provider's `userinfo_endpoint`. For more information, see xref:chap-auth.adoc#oauth-module["OAUTH"]. -[#table-oauth-module-prop] -.OAUTH Module Properties +The options shown in the Admin UI are subdivided into basic and advanced properties. You may need to click Advanced Properties to review those details. + +[#table-oauth-basic] +.OAUTH Module Basic Properties [cols="18%,27%,27%,28%"] |=== |Admin UI Label |Default |Description |Configuration File a|Module Enabled a|false -a|Whether OpenIDM uses the module. -a|authentication.json - -a|OAuth Token Header -a|authToken -a|Name of the HTTP request header that carries the OAuth 2.0 access token (configured via `authTokenHeader`). This header is required; authentication fails if it is absent. -a|authentication.json - -a|OAuth Resolver Header -a|provider -a|Name of the HTTP request header that identifies the provider resolver to use (configured via `authResolverHeader`). The value must match the `name` of an entry in the `resolvers` array. This header is required. +a|Whether to enable the module a|authentication.json -a|Resolvers -a|(none) -a|Required. Array of provider resolver objects (configured via `resolvers`). Each entry configures one OAuth 2.0 provider. At least one entry must be present; see xref:#table-oauth-resolver-prop[OAUTH Resolver Properties] for the properties of each resolver. +a|Client ID +a|blank +a|OAuth 2.0 client ID registered with the provider (`resolvers[].client_id`) a|authentication.json -a|Query on Resource -a|managed/oauth -a|Managed object endpoint to query after the token is validated against the provider (configured via `queryOnResource`). +a|Client Secret +a|blank +a|OAuth 2.0 client secret registered with the provider (`resolvers[].client_secret`) a|authentication.json -a|Authentication ID -a|userName -a|Attribute name in the managed object that OpenIDM uses as the authentication identifier when querying the resource (configured via `propertyMapping.authenticationId`). This is distinct from the resolver-level `authenticationId`, which names the field in the provider's userinfo endpoint response. +a|Scope +a|blank +a|OAuth 2.0 scopes needed to access provider APIs (`resolvers[].scope`) a|authentication.json -a|User Roles -a|authzRoles -a|Attribute in the managed object used for authorization roles (configured via `propertyMapping.userRoles`). +a|Authorization Endpoint +a|https://openam.example.com/openam/oauth2/authorize +a|Provider's authorization endpoint URL (`resolvers[].authorization_endpoint`) a|authentication.json -a|Default User Roles -a|openidm-authorized -a|Roles assigned to all users who authenticate successfully through this module (configured via `defaultUserRoles`). +a|Token Endpoint +a|https://openam.example.com/openam/oauth2/access_token +a|Provider's token endpoint URL (`resolvers[].token_endpoint`) a|authentication.json -a|Augment Security Context -a|(none) -a|Optional script executed after a successful authentication request (configured via `augmentSecurityContext`). +a|User Info Endpoint +a|https://openam.example.com/openam/oauth2/userinfo +a|Provider's userinfo endpoint URL (`resolvers[].userinfo_endpoint`). The access token is validated by calling this endpoint. a|authentication.json -|=== -[#table-oauth-resolver-prop] -.OAUTH Resolver Properties (within `resolvers[]`) -[cols="18%,27%,27%,28%"] -|=== -|Admin UI Label |Default |Description |Configuration File - -a|Name -a|(user-defined) -a|Unique resolver name (configured via `name`). The value sent in the `authResolverHeader` HTTP header must match this name. +a|Authentication ID attribute for the User ID +a|sub +a|Attribute name in the provider's userinfo response that contains the user identifier (`resolvers[].authenticationId`) a|authentication.json -a|Type -a|OAUTH -a|Always `OAUTH` (configured via `type`). +a|Sign-In Button HTML +a|(HTML button markup) +a|HTML markup for the social login button displayed in the UI (`resolvers[].icon`) a|authentication.json -a|Client ID -a|(user-defined) -a|OAuth 2.0 client ID registered with the provider (configured via `client_id`). +a|Query on Resource +a|managed/user +a|Managed object endpoint to query after the token is validated against the provider (`queryOnResource`) a|authentication.json -a|Client Secret -a|(user-defined) -a|OAuth 2.0 client secret registered with the provider (configured via `client_secret`). +a|Default User Roles +a|openidm-authorized +a|Roles assigned to all users who authenticate successfully through this module (`defaultUserRoles`) a|authentication.json -a|Authorization Endpoint -a|(provider URL) -a|Provider's authorization endpoint URL (configured via `authorization_endpoint`). +a|Authentication ID +a|userName +a|Attribute in the managed object used as the authentication identifier when querying the resource (`propertyMapping.authenticationId`) a|authentication.json -a|Token Endpoint -a|(provider URL) -a|Provider's token endpoint URL (configured via `token_endpoint`). +a|Method for Determining Roles +a|User Roles Property +a|How roles are determined for the authenticated user (`propertyMapping`) a|authentication.json -a|Userinfo Endpoint -a|(provider URL) -a|Provider's userinfo endpoint URL (configured via `userinfo_endpoint`). The access token is validated by calling this endpoint. +a|User Roles Property +a|authzRoles +a|Attribute in the managed object used for authorization roles (`propertyMapping.userRoles`) a|authentication.json +|=== -a|Scope -a|["profile", "email"] -a|List of OAuth 2.0 scopes to request (configured via `scope`). -a|authentication.json +[#table-oauth-advanced] +.OAUTH Module Advanced Properties +[cols="18%,27%,27%,28%"] +|=== +|Admin UI Label |Default |Description |Configuration File -a|Authentication ID -a|sub -a|Attribute name in the provider's userinfo endpoint response that contains the user identifier (configured via `authenticationId`; for example, `sub`). This value is mapped to the managed user's authentication identifier. +a|Use Query ID +a|blank +a|A defined `queryId` used to search against the `queryOnResource` endpoint (`queryId`) a|authentication.json -a|Property Map -a|(none) -a|Array of `{source, target}` pairs that map attributes from the provider's userinfo response to attributes on the managed object (configured via `propertyMap`). +a|OAuth Token Header +a|authToken +a|Name of the HTTP request header that carries the OAuth 2.0 access token (`authTokenHeader`). This header is required; authentication fails if it is absent. a|authentication.json -a|Icon -a|(none) -a|HTML markup for the social login button displayed in the UI (configured via `icon`). +a|OAuth Resolver Header +a|provider +a|Name of the HTTP request header that identifies the provider resolver to use (`authResolverHeader`). The value must match the resolver name. a|authentication.json -a|Enabled -a|true -a|Whether this resolver is active (configured via `enabled`). +a|Augment Security Context +a|JavaScript +a|Type of script executed after a successful authentication request (`augmentSecurityContext`). Supports JavaScript or Groovy. a|authentication.json |=== From 08daefddad9339cdeba556ce2d6556bc5eab5a2c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 12:25:46 +0000 Subject: [PATCH 13/14] docs: update copyright year to 2024-2026 for 3A Systems LLC Agent-Logs-Url: https://github.com/OpenIdentityPlatform/OpenIDM/sessions/fd6d62d4-0085-478c-b73b-c0e4e2edc40c Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com> --- .../main/asciidoc/integrators-guide/appendix-auth-modules.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc index d1f3ee717..b0f2c24e4 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc @@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. - Portions Copyright 2024-2025 3A Systems LLC. + Portions Copyright 2024-2026 3A Systems LLC. //// :figure-caption!: From 44f6f8053aebf1eec506cf0f3136c968e3d543b0 Mon Sep 17 00:00:00 2001 From: Valery Kharseko Date: Mon, 30 Mar 2026 10:31:09 +0300 Subject: [PATCH 14/14] Update copyright year for 3A Systems LLC --- openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc index df6ac8fa9..539927918 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc @@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. - Portions Copyright 2024-2025 3A Systems LLC. + Portions Copyright 2024-2026 3A Systems LLC. //// :figure-caption!: