Authentication and Session Module Configuration Details

This appendix includes configuration details for authentication modules described here: "Supported Authentication and Session Modules".

Authentication modules, as configured in the authentication.json file, include a number of properties. Except for the "OPENAM_SESSION Module Configuration Options", Those properties are listed in the following tables:

Session Module
Authentication Property	Property as Listed in the Admin UI	Description
`keyAlias`	(not shown)	Used by the Jetty Web server to service SSL requests.
`privateKeyPassword`	(not shown)	Defaults to `openidm.keystore.password` in `boot.properties`.
`keystoreType`	(not shown)	Defaults to `openidm.keystore.type` in `boot.properties`.
`keystoreFile`	(not shown)	Defaults to `openidm.keystore.location` in `boot.properties`.
`keystorePassword`	(not shown)	Defaults to `openidm.keystore.password` in `boot.properties`
`maxTokenLifeMinutes`	Max Token Life (in seconds)	Maximum time before a session is cancelled. Note the different units for the property and the UI.
`tokenIdleTimeMinutes`	Token Idle Time (in seconds)	Maximum time before an idle session is cancelled. Note the different units for the property and the UI.
`sessionOnly`	Session Only	Whether the session continues after browser restarts.

Static User Module
Authentication Property	Property as Listed in the Admin UI	Description
`enabled`	Module Enabled	Does OpenIDM use the module
`queryOnResource`	Query on Resource	Endpoint hard coded to user `anonymous`
`username`	Static User Name	Default for the static user, `anonymous`
`password`	Static User Password	Default for the static user, `anonymous`
`defaultUserRoles`	Static User Role	Normally set to `openidm-reg` for self-registration

The following table applies to several authentication modules:

Managed User
Internal User
Client Cert
Passthrough
IWA The IWA module includes several Kerberos-related properties listed at the end of the table.

Common Module Properties
Authentication Property	Property as Listed in the Admin UI	Description
`enabled`	Module Enabled	Does OpenIDM use the module
`queryOnResource`	Query on Resource	Endpoint to query
`queryId`	Use Query ID	A defined `queryId` searches against the `queryOnResource` endpoint. An undefined `queryId` against `queryOnResource` with `action=reauthenticate`
`defaultUserRoles`	Default User Roles	Normally blank for managed users
`authenticationId`	Authentication ID	Defines how account credentials are derived from a `queryOnResource` endpoint
`userCredential`	User Credential	Defines how account credentials are derived from a `queryOnResource` endpoint
`userRoles`	User Roles	Defines how account roles are derived from a `queryOnResource` endpoint
`groupMembership`	Group Membership	Provides more information for calculated roles
`groupRoleMapping`	Group Role Mapping	Provides more information for calculated roles
`groupComparisonMethod`	Group Comparison Method	Provides more information for calculated roles
`managedUserLink`	Managed User Link	Applicable mapping (Passthrough module only)
`augmentSecurityContext`	Augment Security Context	Includes a script that is executed only after a successful authentication request.
`servicePrincipal`	Kerberos Service Principal	(IWA only) For more information, see "Configuring IWA Authentication"
`keytabFileName`	Keytab File Name	(IWA only) For more information, see "Configuring IWA Authentication"
`kerberosRealm`	Kerberos Realm	(IWA only) For more information, see "Configuring IWA Authentication"
`kerberosServerName`	Kerberos Server Name	(IWA only) For more information, see "Configuring IWA Authentication"

OPENAM_SESSION Module Configuration Options

The OPENAM_SESSION module uses OpenAM authentication to protect an OpenIDM deployment.

The options shown in the screen are subdivided into basic and advanced properties. You may need to click Advanced Properties to review those details.

The following table describes the label that you see in the Admin UI, the default value (if any), a brief description, and the associated configuration file. If you need the property name, look at the configuration file.

The default values shown depict what you see if you use the OPENAM_SESSION module with the Full Stack Sample. For more information, see "Full Stack Sample - Using OpenIDM in the Open Identity Platform" in the Samples Guide.

OPENAM_SESSION Module Basic Properties
Admin UI Label	Default	Description	Configuration File
Module Enabled	false	Whether to enable the module	authentication.json
Route to OpenAM User Datastore	system/ldap/account	External repository with OpenAM Data Store Information	authentication.json
OpenAM Deployment URL	blank	FQDN of the deployed instance of OpenAM	authentication.json
Require OpenAM Authentication	false	Whether to make the OpenIDM UI redirect users to OpenAM for authentication	ui-configuration.json

OPENAM_SESSION Module Advanced Properties
Admin UI Label	Default	Description	Configuration File
OpenAM Login URL	http://example.com:8081/XUI/#login/	FQDN of the login endpoint of the deployed instance of OpenAM	ui-configuration.json
OpenAM Login Link Text	Login with OpenAM	UI text that links to OpenAM	ui-configuration.json
Default User Roles	openidm-authorized	OpenIDM assigns such roles to the security context of a user	authentication.json
OpenAM User Attribute	uid	User identifier for the OpenAM data store	authentication.json
Authentication ID	uid	User identifier	authentication.json
User Credential	blank	Credential, sometimes a password	authentication.json
User Roles or Group Membership	Select an option	For an explanation, see "Common Module Properties".	authentication.json
Group Membership (if selected)	ldapGroups	Group Membership	authentication.json
Role Name	openidm-admin	Default role for the user, normally a group role mapping	authentication.json
Group Mappings	cn=idmAdmins,ou=Groups,dc=example,dc=com	Mapping from a user to a LDAP entry	authentication.json
TruststorePath Property Name	truststorePath	File path to the OpenIDM truststore	authentication.json
TruststorePath Property Type	security/truststore	Truststore file location, relative to /path/to/openidm	authentication.json (from boot.properties)
Augment Security Context	Javascript	Supports Javascript or Groovy	authentication.json
File Path	auth/populateAsManagedUser.js	Path to security context script, in the `/path/to/openidm/bin/defaults/script` subdirectory	authentication.json

In general, if you add a custom property, the Admin UI writes changes to the authentication.json or ui-configuration.json files.

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 one conf/identityProvider-<name>.json file per provider, not inside the SOCIAL_PROVIDERS module entry. conf/identityProviders.json only holds the catalog of providers that the Admin UI offers; see "SOCIAL_PROVIDERS".

The SOCIAL_PROVIDERS entry is removed from the active authentication module list at startup — it is never initialized as an authenticator itself. Each conf/identityProvider-<name>.json file results in exactly one generated OPENID_CONNECT or OAUTH authentication module, which carries the enabled flag of that provider.

SOCIAL_PROVIDERS Module Basic Properties
Admin UI Label	Default	Description	Configuration File
Module Enabled	true	Controls whether the meta-module activates and generates child modules. If set to `false`, no social provider auth modules are generated.	authentication.json
Default User Roles	openidm-authorized	List of roles inherited by all generated `OAUTH` and `OPENID_CONNECT` modules.	authentication.json
Method for Determining Roles	User Roles Property	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.	authentication.json
User Roles Property	authzRoles	The managed-object attribute used for authorization roles. Applies when Method for Determining Roles is set to `User Roles Property`.	authentication.json

SOCIAL_PROVIDERS Module Advanced Properties
Admin UI Label	Default	Description	Configuration File
Use Query ID	(blank)	A defined `queryId` searches against the `queryOnResource` endpoint. Leave blank to use `action=reauthenticate`.	authentication.json
Augment Security Context — Type	Javascript	Script language for the augment security context script. Supports `Javascript` or `Groovy`.	authentication.json
Augment Security Context — File Path	auth/populateAsManagedUserFromRelationship.js	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.	authentication.json

OPENID_CONNECT Module Configuration Options

The OPENID_CONNECT module authenticates users via an OpenID Connect 1.0 provider. It exchanges an access token for user information from the provider’s userinfo endpoint, then maps the identity to an OpenIDM managed object.

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.

OPENID_CONNECT Module Basic Properties
Admin UI Label	Default	Description	Configuration File
Module Enabled	false	Whether OpenIDM uses this module.	authentication.json
Well-Known Endpoint	(blank)	OIDC Discovery URL (for example, `https://openam.example.com/openam/oauth2/.well-known/openid-configuration`). When provided, the module auto-populates `authorization_endpoint`, `token_endpoint`, and `userinfo_endpoint` from the provider’s discovery document.	authentication.json
Client ID	(blank)	OAuth 2.0 client ID registered with the OIDC provider.	authentication.json
Client Secret	(blank)	OAuth 2.0 client secret registered with the OIDC provider.	authentication.json
Scope	openid	OAuth 2.0 scopes to request. Must include `openid` (for example, `openid email profile`).	authentication.json
Authorization Endpoint	(blank)	Provider’s authorization endpoint URL. Can be omitted when Well-Known Endpoint is set.	authentication.json
Token Endpoint	(blank)	Provider’s token endpoint URL. Can be omitted when Well-Known Endpoint is set.	authentication.json
End Session Endpoint	(blank)	Provider’s end-session (logout) endpoint URL. Can be omitted when Well-Known Endpoint is set.	authentication.json
Sign-In Button HTML	(default button HTML)	HTML markup for the social login button displayed in the OpenIDM UI.	authentication.json
Query on Resource	managed/user	Managed object endpoint to query after token validation (for example, `managed/user`).	authentication.json
Default User Roles	openidm-authorized	Roles assigned to all users who authenticate successfully through this module.	authentication.json
Authentication ID	userName	Attribute in the managed object used as the user identifier, matched against the claim returned from the provider’s userinfo endpoint.	authentication.json
Method for Determining Roles	User Roles Property	How OpenIDM determines the user’s roles after authentication (for example, `User Roles Property`).	authentication.json
User Roles Property	authzRoles	Attribute in the managed object that holds the user’s authorization roles.	authentication.json

OPENID_CONNECT Module Advanced Properties
Admin UI Label	Default	Description	Configuration File
Use Query ID	(blank)	A defined query ID searches against the `queryOnResource` endpoint. Leave blank to use `action=reauthenticate` against `queryOnResource`.	authentication.json
OpenID Connect Header	authToken	Name of the HTTP header that carries the OpenID Connect ID token (JWT) provided by the client.	authentication.json
Augment Security Context	(blank)	Optional script executed after a successful authentication request, used to populate additional security context fields. Supports Javascript or Groovy.	authentication.json

OAUTH Module Configuration Options

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 "OAUTH".

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.

OAUTH Module Basic Properties
Admin UI Label	Default	Description	Configuration File
Module Enabled	false	Whether to enable the module	authentication.json
Client ID	blank	OAuth 2.0 client ID registered with the provider (`resolvers[].client_id`)	authentication.json
Client Secret	blank	OAuth 2.0 client secret registered with the provider (`resolvers[].client_secret`)	authentication.json
Scope	blank	OAuth 2.0 scopes needed to access provider APIs (`resolvers[].scope`)	authentication.json
Authorization Endpoint	https://openam.example.com/openam/oauth2/authorize	Provider’s authorization endpoint URL (`resolvers[].authorization_endpoint`)	authentication.json
Token Endpoint	https://openam.example.com/openam/oauth2/access_token	Provider’s token endpoint URL (`resolvers[].token_endpoint`)	authentication.json
User Info Endpoint	https://openam.example.com/openam/oauth2/userinfo	Provider’s userinfo endpoint URL (`resolvers[].userinfo_endpoint`). The access token is validated by calling this endpoint.	authentication.json
Authentication ID attribute for the User ID	sub	Attribute name in the provider’s userinfo response that contains the user identifier (`resolvers[].authenticationId`)	authentication.json
Sign-In Button HTML	(HTML button markup)	HTML markup for the social login button displayed in the UI (`resolvers[].icon`)	authentication.json
Query on Resource	managed/user	Managed object endpoint to query after the token is validated against the provider (`queryOnResource`)	authentication.json
Default User Roles	openidm-authorized	Roles assigned to all users who authenticate successfully through this module (`defaultUserRoles`)	authentication.json
Authentication ID	userName	Attribute in the managed object used as the authentication identifier when querying the resource (`propertyMapping.authenticationId`)	authentication.json
Method for Determining Roles	User Roles Property	How roles are determined for the authenticated user (`propertyMapping`)	authentication.json
User Roles Property	authzRoles	Attribute in the managed object used for authorization roles (`propertyMapping.userRoles`)	authentication.json

OAUTH Module Advanced Properties
Admin UI Label	Default	Description	Configuration File
Use Query ID	blank	A defined `queryId` used to search against the `queryOnResource` endpoint (`queryId`)	authentication.json
OAuth Token Header	authToken	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.	authentication.json
OAuth Resolver Header	provider	Name of the HTTP request header that identifies the provider resolver to use (`authResolverHeader`). The value must match the resolver name.	authentication.json
Augment Security Context	JavaScript	Type of script executed after a successful authentication request (`augmentSecurityContext`). Supports JavaScript or Groovy.	authentication.json

Authentication and Session Module Configuration Details

OPENAM_SESSION Module Configuration Options

SOCIAL_PROVIDERS Module Configuration Options

OPENID_CONNECT Module Configuration Options

OAUTH Module Configuration Options