Skip to content

Commit 57f83ea

Browse files
CopilotvharsekoCopilot
authored
docs: Add OAUTH authentication module documentation (#136)
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>
1 parent 35fe94d commit 57f83ea

2 files changed

Lines changed: 175 additions & 2 deletions

File tree

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

Lines changed: 112 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
information: "Portions copyright [year] [name of copyright owner]".
1313

1414
Copyright 2017 ForgeRock AS.
15-
Portions Copyright 2024-2025 3A Systems LLC.
15+
Portions Copyright 2024-2026 3A Systems LLC.
1616
////
1717
1818
:figure-caption!:
@@ -291,4 +291,115 @@ a|authentication.json
291291
|===
292292
In general, if you add a custom property, the Admin UI writes changes to the `authentication.json` or `ui-configuration.json` files.
293293
294+
[#oauth-module-details]
295+
=== OAUTH Module Configuration Options
296+
297+
The `OAUTH` module authenticates users via a generic OAuth 2.0 provider. It validates an OAuth 2.0 `access_token` by calling the provider's `userinfo_endpoint`. For more information, see xref:chap-auth.adoc#oauth-module["OAUTH"].
298+
299+
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.
300+
301+
[#table-oauth-basic]
302+
.OAUTH Module Basic Properties
303+
[cols="18%,27%,27%,28%"]
304+
|===
305+
|Admin UI Label |Default |Description |Configuration File
306+
307+
a|Module Enabled
308+
a|false
309+
a|Whether to enable the module
310+
a|authentication.json
311+
312+
a|Client ID
313+
a|blank
314+
a|OAuth 2.0 client ID registered with the provider (`resolvers[].client_id`)
315+
a|authentication.json
316+
317+
a|Client Secret
318+
a|blank
319+
a|OAuth 2.0 client secret registered with the provider (`resolvers[].client_secret`)
320+
a|authentication.json
321+
322+
a|Scope
323+
a|blank
324+
a|OAuth 2.0 scopes needed to access provider APIs (`resolvers[].scope`)
325+
a|authentication.json
326+
327+
a|Authorization Endpoint
328+
a|https://openam.example.com/openam/oauth2/authorize
329+
a|Provider's authorization endpoint URL (`resolvers[].authorization_endpoint`)
330+
a|authentication.json
331+
332+
a|Token Endpoint
333+
a|https://openam.example.com/openam/oauth2/access_token
334+
a|Provider's token endpoint URL (`resolvers[].token_endpoint`)
335+
a|authentication.json
336+
337+
a|User Info Endpoint
338+
a|https://openam.example.com/openam/oauth2/userinfo
339+
a|Provider's userinfo endpoint URL (`resolvers[].userinfo_endpoint`). The access token is validated by calling this endpoint.
340+
a|authentication.json
341+
342+
a|Authentication ID attribute for the User ID
343+
a|sub
344+
a|Attribute name in the provider's userinfo response that contains the user identifier (`resolvers[].authenticationId`)
345+
a|authentication.json
346+
347+
a|Sign-In Button HTML
348+
a|(HTML button markup)
349+
a|HTML markup for the social login button displayed in the UI (`resolvers[].icon`)
350+
a|authentication.json
351+
352+
a|Query on Resource
353+
a|managed/user
354+
a|Managed object endpoint to query after the token is validated against the provider (`queryOnResource`)
355+
a|authentication.json
356+
357+
a|Default User Roles
358+
a|openidm-authorized
359+
a|Roles assigned to all users who authenticate successfully through this module (`defaultUserRoles`)
360+
a|authentication.json
361+
362+
a|Authentication ID
363+
a|userName
364+
a|Attribute in the managed object used as the authentication identifier when querying the resource (`propertyMapping.authenticationId`)
365+
a|authentication.json
366+
367+
a|Method for Determining Roles
368+
a|User Roles Property
369+
a|How roles are determined for the authenticated user (`propertyMapping`)
370+
a|authentication.json
371+
372+
a|User Roles Property
373+
a|authzRoles
374+
a|Attribute in the managed object used for authorization roles (`propertyMapping.userRoles`)
375+
a|authentication.json
376+
|===
377+
378+
[#table-oauth-advanced]
379+
.OAUTH Module Advanced Properties
380+
[cols="18%,27%,27%,28%"]
381+
|===
382+
|Admin UI Label |Default |Description |Configuration File
383+
384+
a|Use Query ID
385+
a|blank
386+
a|A defined `queryId` used to search against the `queryOnResource` endpoint (`queryId`)
387+
a|authentication.json
388+
389+
a|OAuth Token Header
390+
a|authToken
391+
a|Name of the HTTP request header that carries the OAuth 2.0 access token (`authTokenHeader`). This header is required; authentication fails if it is absent.
392+
a|authentication.json
393+
394+
a|OAuth Resolver Header
395+
a|provider
396+
a|Name of the HTTP request header that identifies the provider resolver to use (`authResolverHeader`). The value must match the resolver name.
397+
a|authentication.json
398+
399+
a|Augment Security Context
400+
a|JavaScript
401+
a|Type of script executed after a successful authentication request (`augmentSecurityContext`). Supports JavaScript or Groovy.
402+
a|authentication.json
403+
|===
404+
294405

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

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
information: "Portions copyright [year] [name of copyright owner]".
1313

1414
Copyright 2017 ForgeRock AS.
15-
Portions Copyright 2024-2025 3A Systems LLC.
15+
Portions Copyright 2024-2026 3A Systems LLC.
1616
////
1717
1818
:figure-caption!:
@@ -480,6 +480,68 @@ Set up logins with OpenAM, to work with the related login session cookie, known
480480
IWA::
481481
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"].
482482
483+
[#oauth-module]
484+
OAUTH::
485+
The `OAUTH` module authenticates users via a generic OAuth 2.0 provider by validating an OAuth 2.0 `access_token` against the provider's `userinfo_endpoint`. Unlike the `OPENID_CONNECT` module, it does not use JWT identity tokens.
486+
+
487+
The module requires two HTTP request headers. Their names are configured by the following properties:
488+
+
489+
* `authTokenHeader` — configuration property that specifies the name of the HTTP header carrying the OAuth 2.0 access token (for example, `authToken` in the sample below).
490+
* `authResolverHeader` — configuration property that specifies the name of the HTTP header that identifies the provider resolver (from the `resolvers` list) that should validate the token (for example, `provider` in the sample below).
491+
+
492+
Using two headers allows a single module instance to support multiple OAuth providers simultaneously, each defined as a separate entry in the `resolvers` array.
493+
+
494+
The following sample configuration shows the `OAUTH` module with a single provider resolver:
495+
+
496+
[source, json]
497+
----
498+
{
499+
"name" : "OAUTH",
500+
"enabled" : true,
501+
"properties" : {
502+
"augmentSecurityContext": {
503+
"type" : "text/javascript",
504+
"file" : "auth/populateAsManagedUserFromRelationship.js"
505+
},
506+
"propertyMapping" : {
507+
"userRoles" : "authzRoles",
508+
"authenticationId" : "userName"
509+
},
510+
"defaultUserRoles" : [
511+
"openidm-authorized"
512+
],
513+
"resolvers" : [
514+
{
515+
"name" : "myProvider",
516+
"type" : "OAUTH",
517+
"icon" : "<button class=\"btn btn-lg btn-default btn-block btn-social-provider\"><img src=\"images/provider.png\">Sign in with Provider</button>",
518+
"scope" : ["profile", "email"],
519+
"authenticationId" : "sub",
520+
"propertyMap" : [
521+
{
522+
"source" : "sub",
523+
"target" : "userName"
524+
}
525+
],
526+
"enabled" : true,
527+
"client_id" : "your-client-id",
528+
"client_secret" : "your-client-secret",
529+
"authorization_endpoint" : "https://provider.example.com/oauth2/authorize",
530+
"token_endpoint" : "https://provider.example.com/oauth2/access_token",
531+
"userinfo_endpoint" : "https://provider.example.com/oauth2/userinfo"
532+
}
533+
],
534+
"queryOnResource" : "managed/oauth",
535+
"authTokenHeader" : "authToken",
536+
"authResolverHeader" : "provider"
537+
}
538+
}
539+
----
540+
+
541+
Note that `authenticationId` appears at two different levels with different meanings: inside each `resolvers[]` entry it names the field in the provider's userinfo response that identifies the user (for example, `sub`); at the `propertyMapping` level it names the attribute in the managed object (for example, `userName`) that OpenIDM uses as the authentication identifier after the userinfo fields have been mapped via `propertyMap`. The resolver-level `authenticationId` userinfo field must therefore be included in `propertyMap` and mapped into the managed-object attribute referenced by `propertyMapping.authenticationId`, so that OpenIDM can correlate the resolved user to the `queryOnResource` entry.
542+
+
543+
For detailed property descriptions, see xref:appendix-auth-modules.adoc#oauth-module-details["OAUTH Module Configuration Options"].
544+
483545
--
484546
485547

0 commit comments

Comments
 (0)