docs: Add SOCIAL_PROVIDERS authentication module documentation (#138)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: vharseko <6818498+vharseko@users.noreply.github.com>
Co-authored-by: Valery Kharseko <vharseko@3a-systems.ru>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

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

@@ -291,6 +291,67 @@ 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.
 
+[#social-providers-module-details]
+=== SOCIAL_PROVIDERS Module Configuration Options
+
+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. Each `OPENID_CONNECT` or `OAUTH` provider entry in `conf/identityProviders.json` results in exactly one generated authentication module.
+======
+
+[#social-providers-module-prop-basic]
+.SOCIAL_PROVIDERS Module Basic Properties
+[cols="18%,27%,27%,28%"]
+|===
+|Admin UI Label |Default |Description |Configuration File
+
+a|Module Enabled
+a|true
+a|Controls whether the meta-module activates and generates child modules. If set to `false`, no social provider auth modules are generated.
+a|authentication.json
+
+a|Default User Roles
+a|openidm-authorized
+a|List of roles inherited by all generated `OAUTH` and `OPENID_CONNECT` modules.
+a|authentication.json
+
+a|Method for Determining Roles
+a|User Roles Property
+a|How authorization roles are resolved. When set to `User Roles Property`, the value of the User Roles Property field is used as the attribute name on the managed object.
+a|authentication.json
+
+a|User Roles Property
+a|authzRoles
+a|The managed-object attribute used for authorization roles. Applies when Method for Determining Roles is set to `User Roles Property`.
+a|authentication.json
+
+|===
+
+[#social-providers-module-prop-advanced]
+.SOCIAL_PROVIDERS Module Advanced Properties
+[cols="18%,27%,27%,28%"]
+|===
+|Admin UI Label |Default |Description |Configuration File
+
+a|Use Query ID
+a|(blank)
+a|A defined `queryId` searches against the `queryOnResource` endpoint. Leave blank to use `action=reauthenticate`.
+a|authentication.json
+
+a|Augment Security Context — Type
+a|Javascript
+a|Script language for the augment security context script. Supports `Javascript` or `Groovy`.
+a|authentication.json
+
+a|Augment Security Context — File Path
+a|auth/populateAsManagedUserFromRelationship.js
+a|Path to the security context script, relative to the `bin/defaults/script` directory. This script is inherited by all generated `OAUTH` and `OPENID_CONNECT` modules.
+a|authentication.json
+
+|===
+
 [#openid-connect-module-details]
 === OPENID_CONNECT Module Configuration Options
 

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

@@ -480,6 +480,51 @@ 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"].
 
+[[social-providers-module]]SOCIAL_PROVIDERS::
+The `SOCIAL_PROVIDERS` module is a __meta-module__ (template) that bridges the social identity provider configuration in `conf/identityProviders.json` and the OpenIDM authentication filter. It is not an authenticator itself — instead, at startup it scans all providers registered with the `IdentityProviderService`, removes itself from the active module list, and dynamically generates the corresponding `OPENID_CONNECT` or `OAUTH` authentication modules:
+
++
+* For each provider of type `OPENID_CONNECT`, an `OPENID_CONNECT` auth module is generated with `openIdConnectHeader: "authToken"`.
+* For each provider of type `OAUTH`, an `OAUTH` auth module is generated with `authTokenHeader: "authToken"` and `authResolverHeader: "provider"`.
+
++
+The generated modules inherit the `augmentSecurityContext`, `propertyMapping`, and `defaultUserRoles` values from the `SOCIAL_PROVIDERS` template entry.
+
++
+Providers are configured separately in `conf/identityProviders.json`, or via the Admin UI under *Configure > Social ID Providers*. The `SOCIAL_PROVIDERS` module acts as a single configuration point so that operators do not need to add individual `OPENID_CONNECT` or `OAUTH` entries to `authentication.json` for every social provider.
+
++
+[NOTE]
+======
+Any `OPENID_CONNECT` or `OAUTH` modules that are __explicitly__ defined in `authentication.json` are independent of `SOCIAL_PROVIDERS` and will coexist alongside the dynamically generated modules. They are not managed or removed by `SOCIAL_PROVIDERS`.
+======
+
++
+A sample `SOCIAL_PROVIDERS` configuration is as follows:
++
+[source, json]
+----
+{
+    "name" : "SOCIAL_PROVIDERS",
+    "enabled" : true,
+    "properties" : {
+        "augmentSecurityContext": {
+            "type" : "text/javascript",
+            "file" : "auth/populateAsManagedUserFromRelationship.js"
+        },
+        "propertyMapping" : {
+            "userRoles" : "authzRoles"
+        },
+        "defaultUserRoles" : [
+            "openidm-authorized"
+        ]
+    }
+}
+----
+
++
+For detailed property options, see xref:appendix-auth-modules.adoc#social-providers-module-details["SOCIAL_PROVIDERS Module Configuration Options"].
+
 [#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.