Skip to content

docs: Add SOCIAL_PROVIDERS authentication module documentation #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vharseko merged 10 commits into from
Mar 30, 2026
Merged

docs: Add SOCIAL_PROVIDERS authentication module documentation #138

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
2077e74
Initial plan
Copilot Mar 26, 2026
d1a1f48
docs: Add SOCIAL_PROVIDERS authentication module documentation
Copilot Mar 26, 2026
f57dbd4
Update openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-…
vharseko Mar 26, 2026
f671e6d
docs: address review feedback on SOCIAL_PROVIDERS documentation
Copilot Mar 26, 2026
4e069b0
docs: constrain SOCIAL_PROVIDERS generation description to supported …
Copilot Mar 26, 2026
45d7ad2
docs: restructure SOCIAL_PROVIDERS tables to 4-column OPENAM_SESSION …
Copilot Mar 27, 2026
75b0b8a
docs: expand SOCIAL_PROVIDERS tables with all UI fields in 4-column f…
Copilot Mar 27, 2026
c1a2134
docs: update copyright year to 2026 for 3A Systems LLC
Copilot Mar 27, 2026
27220e1
Update copyright year for 3A Systems LLC
vharseko Mar 30, 2026
3d717a0
Merge remote-tracking branch 'origin/master' into copilot/add-documen…
Copilot Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions openidm-doc/src/main/asciidoc/integrators-guide/appendix-auth-modules.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,4 +291,37 @@ 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, 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.
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“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 uses AI. Check for mistakes.
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“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.

Copilot uses AI. Check for mistakes.
======

[#social-providers-module-prop]
.SOCIAL_PROVIDERS Module Properties
[cols="28%,29%,43%"]
|===
|Authentication Property |Property as Listed in the Admin UI |Description

a|`enabled`
a|Module Enabled
a|Must be `true` for the meta-module to activate and generate child modules. If `false` or absent, no social provider auth modules are generated.
Comment thread
vharseko marked this conversation as resolved.
Outdated

a|`augmentSecurityContext`
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
a|Augment Security Context
a|Script inherited by all generated `OAUTH` and `OPENID_CONNECT` modules. Typically set to `auth/populateAsManagedUserFromRelationship.js`.

a|`propertyMapping.userRoles`
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
a|User Roles
a|Attribute used for authorization roles, inherited by all generated modules. Usually set to `authzRoles`.

a|`defaultUserRoles`
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
a|Default User Roles
a|List of roles inherited by all generated modules. Usually set to `["openidm-authorized"]`.
|===


46 changes: 46 additions & 0 deletions openidm-doc/src/main/asciidoc/integrators-guide/chap-auth.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,52 @@ 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::
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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::

Copilot uses AI. Check for mistakes.
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"].

--


Expand Down
Loading