Single sign on configuration using generic OpenID Connection plugin

Product:	IMiS/ARChive
Release:	Since 10.3.2210
Date:	06/19/2023

Case:

Generic OpenID Connection (OIDC) plugin enables single sign on (SSO) authentication method, using external identity provider (IDP). In this article we present different configuration examples, how to configure generic OpenID Connection plugin to establish SSO.

Description:

Generic OpenID Connection plugin validates OpenID JWT token end extract information from it to resolve IMiS ARChive user identity. Plugin is configured with xml configuration tags, which are listed in next sections.

Network related xml tags:

"<ConnectionTimeout>": connection timeout in milliseconds (default 30000 milliseconds).
"<ReadTimeout>": read response timeout in milliseconds (default 30000 milliseconds).
"<HttpUserAgent>": "User-Agent" http header value (default is not present).
"<SSLKSType>": SSL keystore type (supports all keystore types from Java).
"<SSLKSPassword>": SSL keystore password.
"<SSLTSType>": SSL truststore type (supports all truststore types from Java). Use "IAKS" type for using internal certificate store from IMiS ARChive Server.
"<SSLTSFile>": SSL truststore full path. If "IAKS" type is used, tag is omitted.
"<SSLTSPassword>": SSL truststore password. If "IAKS" type is used, tag is omitted.
"<SSLProtocols>": supported SSL protocols. Multiple values must be separated with ",". If multiple values are used, they are processed in the same order as they are defined in tag.
"<Proxy>": represent root tag for proxy support. Tag must contain "<Address>" tag, which represents proxy URL with port. Optionally, there may be "<Username>" and "<Password>" tags if proxy authentication is required.

Clock skew xml tags:

"<ClockSkew>": Clock skew (in seconds) which is used when JWT time validity is checked (default 0 seconds).

Audience xml tags:

"<AudienceBlacklist>": List of audience identifications, which are not allowed to be logged in using OpenID JWT (default empty).
"<AudienceWhitelist>": List of audience identifications, which are allowed to be logged in using OpenID JWT (default empty).

If blacklist is defined, then such audience has denied access to OIDC authentication on IMiS ARChive server. If whitelist is defined, then only whitelisted audience is allowed to authenticate using OIDC token. Evaluation order is next: blacklist, whitelist.

Generic OIDC plugin xml tags:

"<ProcessUnregisteredClaims>": If set to true, plugin will process additional claims, which are not part of OIDC standard.
"<OfflineJWKS>": Path to offline file with JWT keys.
"<HMACSecret>": Secret value in case if identity provider uses HMAC protection.
"<IssuerIdentifier>": Identity provider identifier (if JWKS is not used).
"<OnlineJWKS>": URL to online JWT keys.
"<UserInfoEndpoint>": UserInfo endpoint URL for access token validation.
"<WellKnownDocument>": URL address to OIDC well known document where all required information about identity provider is present.
"<ClientId>": Single client identifier, which is checked against "audience" and "authorized party". Prefferable way, if IDP (and client) supports multiple audience request during IDP authentication. Check examples for additional information.
"<ImpersionateClientId>": List of client identifiers, which are impersonated by plugin and checked against "audience" and "authorized party".
"<Debug>": True to write debug messages to server log (default to false).

Next sections represent supported fields, which may be used during field translation for identity resolving.

List of supported claims in JWT header:

"alg": JWT signature algorithm.
"typ": JWT type.
"cty": JWT content type.
"kid": JWT signature key identifier.

List of supported claims in JWT body:

"iss": Issuer identifier.
"sub": Subject identifier.
"aud": Audience, for which JWT is valid.
"exp": Token expiration timestamp.
"iat": Token signing timestamp.
"auth_time": Subject authentication timestamp.
"nonce": Random string, used during client authentication.
"acr": Authentication Context Class Reference.
"amr": Authentication Methods References.
"azp": Authorized party.
"at_hash": Access token hash.
"c_hash": "Code" request hash value.
"nbf": Token is not valid before timestamp.
"jti": JWT id.
"name": Name and surname of the authenticated user.
"given_name": Name of authenticated user.
"family_name": Surname of authenticated user.
"middle_name": Middle name od authenticated user.
"nickname": Authenticated user nickname.
"preferred_username": Default username.
"profile": URL to user profile.
"picture": URL to user picture.
"website": URL to user web page.
"email": User email.
"email_verified": True/False if user email is verified by identity provider.
"gender": User gender.
"birthdate": User birth date.
"zoneinfo": User timezone info.
"locale": Locale information.
"phone_number": User phone number.
"phone_number_verified": True/False if phone number is verified by identity provider.

IMiS ARChive server also works as identity provider, because it contains internal directory with users and groups. To successfully map identity from IDP with identity in IMiS ARChive server, identity linking concept was introduced. User must first link local identity on IMiS ARChive server with identity, provided by IDP. User first authenticate to IMiS ARChive server, using local credentials, external authentication mechanism or any other authentication type, supported by IMiS ARChive server. Then it links current identity with IDP identity by logging to IDP. After successful logging to IDP, local identity and IDP identity are linked, and user can use SSO mechanism on next login to IMiS ARChive server.

OIDC specifications describes combination of "subject" and "issuer" as globally unique identifier across all IDP, and that combination is also preferred by IMiS ARChive plugin configuration, although administrator may configure plugin in different way. IMiS ARChive plugin configuration fields for "subject" and "issuer" configuration are next:

"sys:dir:lid:Subject": Represents linked identity subject.
"sys:dir:lid:Issuer": Represents linked identity issuer.

Each plugin field can also be additionally manipulated by using embedded translation rules and javascript. For details, check linked articles in "related documents" section.

Generic OIDC plugin contains two implementations:

GenericImpersonationOIDCATValidator: Implementation validates "id token", validates "access token" validity and extracts linked identity according to plugin configuration.
GenericImpersonationOIDCValidator: Implementation validates "id token".

Both implementations use impersonation concept. In this case, plugin acts as client, which checks "id token" signature and required field, if GenericImpersonationOIDCATValidator is used, it also checks data from "user info endpoint" (by using "access token") to match data in "id token". Next few examples demonstrate different OIDC configurations with Google and Auth0 IDP providers.

Example 1: Using GenericImpersonationOIDCATValidator on Google IDP with multiple clients, which does not support multiple audience request:

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.GenericImpersonationOIDCATValidator</Class>
<ImpersionateClientId>first-client-application-id.apps.googleusercontent.com</ImpersionateClientId>
<ImpersionateClientId>second-client-application-id.apps.googleusercontent.com</ImpersionateClientId>
<ImpersionateClientId>third-client-application-id.apps.googleusercontent.com</ImpersionateClientId>
<WellKnownDocument>https://accounts.google.com/.well-known/openid-configuration</WellKnownDocument>
<Field key="sys:dir:lid:Subject" type="string">sub</Field>
<Field key="sys:dir:lid:Issuer" type="string">iss</Field>
</Arguments>

Each client must be registered on Google IDP to obtain application id.

Example 2: Using GenericImpersonationOIDCATValidator on Google IDP with multiple clients, which supports multiple audience request:

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.GenericImpersonationOIDCATValidator</Class>
<ClientId>imis-archive-server-application-id.apps.googleusercontent.com</ClientId>
<WellKnownDocument>https://accounts.google.com/.well-known/openid-configuration</WellKnownDocument>
<Field key="sys:dir:lid:Subject" type="string">sub</Field>
<Field key="sys:dir:lid:Issuer" type="string">iss</Field>
</Arguments>

With this configuration, IMiS ARChive server must be registered as application on Google IDP to obtain application id. Each client, which authenticates to IMiS ARChive with JWT token, must request additional IMiS ARChive audience during authentication with IDP, so that "id token" contains "ClientId" data in "aud" field.

Example 3: Using GenericImpersonationOIDCValidator on Auth0 IDP with multiple clients and enabled debugging (multiple audience and user endpoint not supported)

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.GenericImpersonationOIDCValidator</Class>
<ImpersionateClientId>first-client-application-id</ImpersionateClientId>
<ImpersionateClientId>second-client-application-id</ImpersionateClientId>
<ImpersionateClientId>third-client-application-id</ImpersionateClientId>
<WellKnownDocument>https://registered-tenant.auth0.com/.well-known/openid-configuration</WellKnownDocument>
<Field key="sys:dir:lid:Subject" type="string">sub</Field>
<Field key="sys:dir:lid:Issuer" type="string">iss</Field>
<Debug>true</Debug>
</Arguments>

Example 4: Blacklisting

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.GenericImpersonationOIDCValidator</Class>
<ImpersionateClientId>first-client-application-id</ImpersionateClientId>
<ImpersionateClientId>second-client-application-id</ImpersionateClientId>
<ImpersionateClientId>third-client-application-id</ImpersionateClientId>
<WellKnownDocument>https://registered-tenant.auth0.com/.well-known/openid-configuration</WellKnownDocument>
<AudienceBlacklist>first-client-application-id</AudienceBlacklist>
<AudienceBlacklist>second-client-application-id</AudienceBlacklist>
<Field key="sys:dir:lid:Subject" type="string">sub</Field>
<Field key="sys:dir:lid:Issuer" type="string">iss</Field>
<Debug>true</Debug>
</Arguments>

Only "third-client-application-id" client is allowed to connect to IMiS ARChive server, using OIDC token.

Example 5: Whitelisting

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.GenericImpersonationOIDCValidator</Class>
<ImpersionateClientId>first-client-application-id</ImpersionateClientId>
<ImpersionateClientId>second-client-application-id</ImpersionateClientId>
<ImpersionateClientId>third-client-application-id</ImpersionateClientId>
<WellKnownDocument>https://registered-tenant.auth0.com/.well-known/openid-configuration</WellKnownDocument>
<AudienceWhitelist>first-client-application-id</AudienceWhitelist>
<AudienceWhitelist>second-client-application-id</AudienceWhitelist>
<Field key="sys:dir:lid:Subject" type="string">sub</Field>
<Field key="sys:dir:lid:Issuer" type="string">iss</Field>
<Debug>true</Debug>
</Arguments>

Only "first-client-application-id" and "second-client-application-id" clients are allowed to connect to IMiS ARChive server using OIDC token.

Example 6: Whitelisting and blacklisting:

<Arguments>
<Class>com.imis.imisarc.server.aaa.impl.GenericImpersonationOIDCValidator</Class>
<ImpersionateClientId>first-client-application-id</ImpersionateClientId>
<ImpersionateClientId>second-client-application-id</ImpersionateClientId>
<ImpersionateClientId>third-client-application-id</ImpersionateClientId>
<WellKnownDocument>https://registered-tenant.auth0.com/.well-known/openid-configuration</WellKnownDocument>
<AudienceWhitelist>first-client-application-id</AudienceWhitelist>
<AudienceWhitelist>second-client-application-id</AudienceWhitelist>
<AudienceBlacklist>second-client-application-id</AudienceBlacklist>
<Field key="sys:dir:lid:Subject" type="string">sub</Field>
<Field key="sys:dir:lid:Issuer" type="string">iss</Field>
<Debug>true</Debug>
</Arguments>

Only "first-client-application-id" client is allowed to connect to IMiS ARChive server using OIDC token.

- Generic connector field evaluation using javascript

Database 'IMiS Knowledge database', View 'By Product', Document 'Generic connector field evaluation using embedded translation rules'

- Generic connector field evaluation using embedded translation rules

| Back | Main view