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..8f3a15a5b 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!: @@ -291,4 +291,111 @@ 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. +[#openid-connect-module-details] +=== OPENID_CONNECT Module Configuration Options + +The `OPENID_CONNECT` module authenticates users via an OpenID Connect 1.0 provider. It exchanges an access token for user information from the provider's userinfo endpoint, then maps the identity to an OpenIDM managed object. + +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. + +The following table describes the label that you see in the Admin UI, the default value (if any), a brief description, and the associated configuration file. If you need the property name, look at the configuration file. + +[#table-openid-connect-basic] +.OPENID_CONNECT Module Basic Properties +[cols="18%,27%,27%,28%"] +|=== +|Admin UI Label |Default |Description |Configuration File + +a|Module Enabled +a|false +a|Whether OpenIDM uses this module. +a|authentication.json + +a|Well-Known Endpoint +a|(blank) +a|OIDC Discovery URL (for example, `https://openam.example.com/openam/oauth2/.well-known/openid-configuration`). When provided, the module auto-populates `authorization_endpoint`, `token_endpoint`, and `userinfo_endpoint` from the provider's discovery document. +a|authentication.json + +a|Client ID +a|(blank) +a|OAuth 2.0 client ID registered with the OIDC provider. +a|authentication.json + +a|Client Secret +a|(blank) +a|OAuth 2.0 client secret registered with the OIDC provider. +a|authentication.json + +a|Scope +a|openid +a|OAuth 2.0 scopes to request. Must include `openid` (for example, `openid email profile`). +a|authentication.json + +a|Authorization Endpoint +a|(blank) +a|Provider's authorization endpoint URL. Can be omitted when Well-Known Endpoint is set. +a|authentication.json + +a|Token Endpoint +a|(blank) +a|Provider's token endpoint URL. Can be omitted when Well-Known Endpoint is set. +a|authentication.json + +a|End Session Endpoint +a|(blank) +a|Provider's end-session (logout) endpoint URL. Can be omitted when Well-Known Endpoint is set. +a|authentication.json + +a|Sign-In Button HTML +a|(default button HTML) +a|HTML markup for the social login button displayed in the OpenIDM UI. +a|authentication.json + +a|Query on Resource +a|managed/user +a|Managed object endpoint to query after token validation (for example, `managed/user`). +a|authentication.json + +a|Default User Roles +a|openidm-authorized +a|Roles assigned to all users who authenticate successfully through this module. +a|authentication.json + +a|Authentication ID +a|userName +a|Attribute in the managed object used as the user identifier, matched against the claim returned from the provider's userinfo endpoint. +a|authentication.json + +a|Method for Determining Roles +a|User Roles Property +a|How OpenIDM determines the user's roles after authentication (for example, `User Roles Property`). +a|authentication.json + +a|User Roles Property +a|authzRoles +a|Attribute in the managed object that holds the user's authorization roles. +a|authentication.json +|=== + +[#table-openid-connect-advanced] +.OPENID_CONNECT Module Advanced Properties +[cols="18%,27%,27%,28%"] +|=== +|Admin UI Label |Default |Description |Configuration File + +a|Use Query ID +a|(blank) +a|A defined query ID searches against the `queryOnResource` endpoint. Leave blank to use `action=reauthenticate` against `queryOnResource`. +a|authentication.json + +a|OpenID Connect Header +a|authToken +a|Name of the HTTP header that carries the OpenID Connect ID token (JWT) provided by the client. +a|authentication.json + +a|Augment Security Context +a|(blank) +a|Optional script executed after a successful authentication request, used to populate additional security context fields. Supports Javascript or Groovy. +a|authentication.json +|=== 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..debadd7ee 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,56 @@ 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"]. +[#openid-connect-module] +OPENID_CONNECT:: +The `OPENID_CONNECT` module authenticates users via an OpenID Connect 1.0 provider. It reads an OpenID Connect ID token (JWT) from an HTTP header (configured via `openIdConnectHeader`), validates it against the configured OIDC provider endpoints, and maps the authenticated identity to an OpenIDM managed object. ++ +The module uses a single OIDC provider configuration from the first entry in the `resolvers` array (`resolvers[0]`). Although `resolvers` is defined as an array, only one resolver is supported and used per `OPENID_CONNECT` module instance; that entry configures the provider with its own `client_id`, `client_secret`, and endpoint URLs. When a `well-known` discovery URL is provided, the module auto-populates the `authorization_endpoint`, `token_endpoint`, and `userinfo_endpoint` from the provider's OIDC discovery document. ++ +The following excerpt shows a sample `OPENID_CONNECT` configuration using Google as the identity provider: ++ + +[source, json] +---- +{ + "name" : "OPENID_CONNECT", + "enabled" : true, + "properties" : { + "augmentSecurityContext": { + "type" : "text/javascript", + "file" : "auth/populateAsManagedUserFromRelationship.js" + }, + "propertyMapping" : { + "userRoles" : "authzRoles", + "authenticationId" : "_id" + }, + "defaultUserRoles" : [ + "openidm-authorized" + ], + "resolvers" : [ + { + "name" : "google", + "type" : "OPENID_CONNECT", + "icon" : "", + "scope" : ["openid", "email", "profile"], + "authenticationId" : "sub", + "enabled" : true, + "client_id" : "your-client-id.apps.googleusercontent.com", + "client_secret" : "your-client-secret", + "well-known" : "https://accounts.google.com/.well-known/openid-configuration", + "authorization_endpoint" : "https://accounts.google.com/o/oauth2/v2/auth", + "token_endpoint" : "https://oauth2.googleapis.com/token", + "userinfo_endpoint" : "https://openidconnect.googleapis.com/v1/userinfo" + } + ], + "queryOnResource" : "managed/google", + "openIdConnectHeader" : "authToken" + } +} +---- + +For detailed options, see xref:appendix-auth-modules.adoc#openid-connect-module-details["OPENID_CONNECT Module Configuration Options"]. + --