docs: Add SOCIAL_PROVIDERS authentication module documentation

[Copilot]

• Restructure SOCIAL_PROVIDERS tables to 4-column format matching the Admin UI screenshot
• Split into Basic Properties and Advanced Properties tables
• Add missing Basic fields: Default User Roles, Method for Determining Roles, User Roles Property
• Add missing Advanced fields: Use Query ID, Augment Security Context (Type, File Path)
• Update copyright year range to 2024-2026 for 3A Systems LLC

Original prompt

Task

Add documentation for the SOCIAL_PROVIDERS 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 SOCIAL_PROVIDERS module is implemented in:

• openidm-authnfilter/src/main/java/org/forgerock/openidm/auth/AuthenticationService.java — methods getSocialAuthTemplate() and amendAuthConfig() and inner class SocialAuthModuleConfigFactory
• openidm-authnfilter/src/test/resources/config/authentication.json — example config
• openidm-identity-provider/src/main/java/org/forgerock/openidm/idp/impl/IdentityProviderService.java — the service that provides provider configurations
• openidm-identity-provider/src/main/java/org/forgerock/openidm/idp/config/ProviderConfig.java — provider configuration model
• UI translation strings (translation.json) describe it as: "Enables authentication for all defined social providers"

How it works (from code analysis — AuthenticationService.java)

SOCIAL_PROVIDERS is a meta-module / template — it has no authentication implementation of its own. When OpenIDM starts and loads authentication.json:

1. getSocialAuthTemplate() scans authModules for an entry with "name": "SOCIAL_PROVIDERS" that is enabled: true
2. amendAuthConfig() is called: the SOCIAL_PROVIDERS entry is removed from the active module list
3. For each provider registered in the IdentityProviderService (configured via identityProvider.json), a new auth module is dynamically generated using the SocialAuthModuleConfigFactory:
   • If the provider type is OPENID_CONNECT → an OPENID_CONNECT auth module is created with openIdConnectHeader: "authToken"
   • If the provider type is OAUTH → an OAUTH auth module is created with authTokenHeader: "authToken" and authResolverHeader: "provider"
4. The generated modules inherit augmentSecurityContext, propertyMapping, and defaultUserRoles from the SOCIAL_PROVIDERS template

This design means operators only need to configure one SOCIAL_PROVIDERS entry in authentication.json, and add providers to identityProvider.json — OpenIDM will automatically generate and activate the corresponding OAUTH/OPENID_CONNECT auth modules.

Key properties of the SOCIAL_PROVIDERS module template:

• enabled — must be true for the meta-module to activate
• augmentSecurityContext — script inherited by all generated modules (typically auth/populateAsManagedUserFromRelationship.js)
• propertyMapping.userRoles — inherited by generated modules (usually authzRoles)
• defaultUserRoles — inherited by generated modules (usually ["openidm-authorized"])

Note: SOCIAL_PROVIDERS does NOT have resolvers, queryOnResource, openIdConnectHeader, or authTokenHeader in its own config — those are injected by the factory when generating child modules.

Example configuration (from authentication.json test resource):

{
    "name" : "SOCIAL_PROVIDERS",
    "enabled" : true,
    "properties" : {
        "augmentSecurityContext": {
            "type" : "text/javascript",
            "file" : "auth/populateAsManagedUserFromRelationship.js"
        },
        "propertyMapping" : {
            "userRoles" : "authzRoles"
        },
        "defaultUserRoles" : [
            "openidm-authorized"
        ]
    }
}

The identity providers themselves are defined in a separate conf/identityProviders.json file (managed by IdentityProviderService). The SOCIAL_PROVIDERS module acts as a bridge between that configuration and the authentication filter.

Changes Required

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

In the section [#supported-auth-modules] ("Supported Authentication Modules"), add a new entry documenting the SOCIAL_PROVIDERS module. Recommended placement: before the OPENID_CONNECT and OAUTH entries, ideally after IWA::.

The documentation should clearly explain:

• That SOCIAL_PROVIDERS is a meta-module / template, not a standalone authenticator
• How it works at startup: scans IdentityProviderService, removes itself, generates OPENID_CONNECT and OAUTH modules dynamically
• That providers are configured in conf/identityProviders.json (or via Admin UI under Configure > Social ID Providers)
• The properties it accepts as a template (which are inherited by generated child modules)
• The relationship to OPENID_CONNECT and OAUTH modules
• A warning/note that explicitly configured OPENID_CONNECT/OAUTH modules in authentication.json are NOT managed by SOCIAL_PROVIDERS and will coexist independently
• 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 with a properties table for the SOCIAL_PROVIDERS module. The table ...

This pull request was created from Copilot chat.

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[Copilot]

Pull request overview

Adds Integrators Guide documentation for the SOCIAL_PROVIDERS authentication meta-module, explaining how it generates OPENID_CONNECT/OAUTH modules dynamically from configured identity providers.

Changes:

• Documented SOCIAL_PROVIDERS in the “Supported Authentication Modules” list, including behavior, caveats, and a sample authentication.json entry.
• Added an appendix section describing SOCIAL_PROVIDERS configuration options and inherited properties.

Reviewed changes

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

File	Description
openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc	Adds a new SOCIAL_PROVIDERS entry describing startup generation behavior and linking to appendix details.
openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc	Adds a new section documenting SOCIAL_PROVIDERS properties and how they apply to generated modules.

---

💡 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 4 comments.

---

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

[Copilot]

These entries read like top-level authentication module properties, but the example configuration places them under the module’s properties object. To prevent misconfiguration, clarify the expected JSON paths (for example properties.augmentSecurityContext, properties.propertyMapping.userRoles, properties.defaultUserRoles) or add a short sentence above the table stating that these keys are under the module’s properties section.

[Copilot]

These entries read like top-level authentication module properties, but the example configuration places them under the module’s properties object. To prevent misconfiguration, clarify the expected JSON paths (for example properties.augmentSecurityContext, properties.propertyMapping.userRoles, properties.defaultUserRoles) or add a short sentence above the table stating that these keys are under the module’s properties section.

[Copilot]

These entries read like top-level authentication module properties, but the example configuration places them under the module’s properties object. To prevent misconfiguration, clarify the expected JSON paths (for example properties.augmentSecurityContext, properties.propertyMapping.userRoles, properties.defaultUserRoles) or add a short sentence above the table stating that these keys are under the module’s properties section.

[Copilot]

For more reliable cross-referencing in AsciiDoc description lists, consider attaching the anchor directly to the term (e.g., [[social-providers-module]]SOCIAL_PROVIDERS::) rather than using a block attribute line. This avoids ambiguity about whether the anchor targets the list block vs. the specific list item.

Suggested change

	[#social-providers-module]
	SOCIAL_PROVIDERS::
	[[social-providers-module]]SOCIAL_PROVIDERS::

[vharseko]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all review feedback in f671e6d:

• Fixed anchor syntax in chap-auth.adoc to inline format ([[social-providers-module]]SOCIAL_PROVIDERS::)
• Split the appendix properties table to clearly separate the top-level enabled property from the properties-nested fields (properties.augmentSecurityContext, properties.propertyMapping.userRoles, properties.defaultUserRoles), with an explanatory sentence between the two tables

[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]

“Each provider entry … results in exactly one generated OPENID_CONNECT or OAUTH module” is too strong as written unless all possible provider entries are guaranteed to be only those two types. To avoid documenting incorrect behavior, constrain this to supported provider types (for example: “each OPENID_CONNECT/OAUTH provider entry…”) or document what happens for unsupported provider types (ignored, error, etc.).

Suggested change

	The `SOCIAL_PROVIDERS` module is a meta-module (template) that dynamically generates `OPENID_CONNECT` and `OAUTH` authentication modules at startup, one for each provider registered in the `IdentityProviderService`. The identity provider configurations themselves (client IDs, client secrets, authorization endpoints, etc.) are defined in `conf/identityProviders.json`, not inside the `SOCIAL_PROVIDERS` module entry.
	[NOTE]
	======
	The `SOCIAL_PROVIDERS` entry is removed from the active authentication module list at startup — it is never initialized as an authenticator itself. Each provider entry in `conf/identityProviders.json` results in exactly one generated `OPENID_CONNECT` or `OAUTH` module.
	The `SOCIAL_PROVIDERS` module is a meta-module (template) that dynamically generates `OPENID_CONNECT` and `OAUTH` authentication modules at startup for supported providers registered in the `IdentityProviderService`. The identity provider configurations themselves (client IDs, client secrets, authorization endpoints, etc.) are defined in `conf/identityProviders.json`, not inside the `SOCIAL_PROVIDERS` module entry.
	[NOTE]
	======
	The `SOCIAL_PROVIDERS` entry is removed from the active authentication module list at startup — it is never initialized as an authenticator itself. For each identity provider entry in `conf/identityProviders.json` that is configured as an `OPENID_CONNECT` or `OAUTH` provider, the system generates exactly one corresponding authentication module.

[Copilot]

“Each provider entry … results in exactly one generated OPENID_CONNECT or OAUTH module” is too strong as written unless all possible provider entries are guaranteed to be only those two types. To avoid documenting incorrect behavior, constrain this to supported provider types (for example: “each OPENID_CONNECT/OAUTH provider entry…”) or document what happens for unsupported provider types (ignored, error, etc.).

Suggested change

	The `SOCIAL_PROVIDERS` entry is removed from the active authentication module list at startup — it is never initialized as an authenticator itself. Each provider entry in `conf/identityProviders.json` results in exactly one generated `OPENID_CONNECT` or `OAUTH` module.
	The `SOCIAL_PROVIDERS` entry is removed from the active authentication module list at startup — it is never initialized as an authenticator itself. Each `OPENID_CONNECT` or `OAUTH` provider entry in `conf/identityProviders.json` results in exactly one generated authentication module.

[vharseko]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied in 4e069b0. The intro now says "for supported providers" and the NOTE now reads "Each OPENID_CONNECT or OAUTH provider entry in conf/identityProviders.json results in exactly one generated authentication module," avoiding the overly broad implication that all provider types produce a module.