docs: Add OPENID_CONNECT authentication module documentation

[Copilot]

• Restructure OPENID_CONNECT tables into Basic/Advanced split matching OPENAM_SESSION 4-column format
• Update copyright year to 2024-2026 for 3A Systems LLC in the modified file

Original prompt

Task

Add documentation for the OPENID_CONNECT authentication module to the integrators guide. This module is fully implemented in the codebase but is completely absent from the current documentation (chap-auth.adoc and appendix-auth-modules.adoc).

Background

The OPENID_CONNECT module is implemented in:

• openidm-authnfilter/src/main/java/org/forgerock/openidm/auth/AuthenticationService.java — generated dynamically from SOCIAL_PROVIDERS template or configured explicitly
• openidm-authnfilter/src/main/java/org/forgerock/openidm/auth/modules/oauth/OAuthModule.java — underlying module implementation
• openidm-ui/openidm-ui-admin/src/main/js/org/forgerock/openidm/ui/admin/authentication/modules/OPENID_CONNECT.js — Admin UI view
• Test configs: openidm-authnfilter/src/test/resources/config/authentication.json and amendedAuthentication.json
• The UI translation strings (translation.json) describe it as: "Supports OpenID Connect 1.0"

How it works (from code analysis)

The OPENID_CONNECT module authenticates users via an OpenID Connect 1.0 provider. It reads a JWT token from a configured HTTP header (openIdConnectHeader), validates it against the configured OIDC provider endpoints, and maps the user identity to an OpenIDM managed object.

Key properties extracted from code:

• openIdConnectHeader — HTTP header carrying the OIDC token (e.g., authToken)
• queryOnResource — managed object resource to query (e.g., managed/google)
• resolvers — array of OIDC provider configurations (one resolver per module instance), each with:
  • name — unique resolver name
  • type — always OPENID_CONNECT
  • client_id / client_secret
  • authorization_endpoint
  • token_endpoint
  • userinfo_endpoint
  • well-known — optional OIDC discovery URL that auto-populates endpoints
  • scope — list of OAuth scopes (must include openid)
  • authenticationId — attribute used as user ID (e.g., _id, sub)
  • icon — HTML for the social login button
  • enabled — whether this resolver is active
• propertyMapping.authenticationId — maps the OIDC claim to OpenIDM identity
• propertyMapping.userRoles — maps to OpenIDM roles (usually authzRoles)
• defaultUserRoles — roles assigned on successful authentication
• augmentSecurityContext — optional script to run post-authentication

Example configuration (from amendedAuthentication.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" : "<button class=\"btn btn-lg btn-default btn-block btn-social-provider\"><img src=\"images/google.png\">Sign in with Google</button>",
                "scope" : ["openid", "email", "profile"],
                "authenticationId" : "_id",
                "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"
    }
}

Changes Required

1. openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc

In the section [#supported-auth-modules] ("Supported Authentication Modules"), after the IWA:: entry (before the closing --), add a new entry documenting the OPENID_CONNECT module. It should follow the same style as existing entries (definition list item with ::, description, sample config JSON block, and cross-reference to the appendix for detailed properties).

The documentation should explain:

• What the module does (authenticates users via OpenID Connect 1.0 providers)
• That it reads a token from an HTTP header configured via openIdConnectHeader
• The resolvers array concept (one OIDC provider per entry)
• The optional well-known URL that auto-populates endpoints
• A sample configuration JSON block
• Cross-reference to the appendix for property details

2. openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc

Add a new section (similar in structure to the existing OPENAM_SESSION section) with a properties table for the OPENID_CONNECT module. The t...

This pull request was created from Copilot chat.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

Adds missing Integrators Guide documentation for the already-implemented OPENID_CONNECT authentication module.

Changes:

• Documented OPENID_CONNECT under “Supported Authentication Modules” with a sample configuration and appendix cross-reference.
• Added an appendix section documenting OPENID_CONNECT module-level and resolver-level configuration properties.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc	Adds a new OPENID_CONNECT:: entry with behavior overview and example config.
openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc	Adds a new appendix section and tables describing OPENID_CONNECT options.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

resolvers[].authenticationId is described as an “OIDC claim or managed object attribute”, but this field corresponds to a property/claim in the identity provider profile/ID token used to identify the subject (it’s used to read from the provider profile). It shouldn’t be described as a managed object attribute here; clarify it’s the provider profile claim name (for example, sub).

Suggested change

	a|OIDC claim or managed object attribute used as the user identifier (for example, `sub` or `_id`).
	a|Claim name in the identity provider profile or ID token used as the user identifier (for example, `sub`).

[vharseko]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Done in 29f1292 — resolvers[].authenticationId now reads "Claim name in the identity provider profile or ID token used as the user identifier (for example, sub)."

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This example sets resolvers[0].authenticationId to _id, which reads like a managed object attribute rather than an identity-provider claim. In the new appendix table, resolvers[].authenticationId is documented as a claim name (e.g., sub). To avoid integrator confusion, update the example to use a realistic claim name (e.g., sub) for the resolver, and keep propertyMapping.authenticationId for the managed-object-side identifier (e.g., _id) if that’s the intended mapping.

Suggested change

	"authenticationId" : "_id",
	"authenticationId" : "sub",

[Copilot]

Both the module and resolver levels use the name authenticationId, but they refer to different concepts (managed-object attribute vs. IdP claim). The module-level description is currently accurate but incomplete; it should explicitly describe how it relates to the resolver-level claim (e.g., “managed object attribute to match against the resolver’s authenticationId claim”). This makes it clear which side of the mapping each property controls.

Suggested change

	a|Attribute in the managed object used as the user identifier.
	a|Attribute in the managed object used as the user identifier, to be matched against the resolver's `authenticationId` claim.

[vharseko]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Done in 9790f10:

• resolvers[0].authenticationId in the example is now "sub" (an IdP claim name)
• propertyMapping.authenticationId description now reads "Attribute in the managed object used as the user identifier, to be matched against the resolver's authenticationId claim."