The OAuth worker allows iCM to act as an OpenID Connect Provider (ie as an authentication server) for other services. That means website users registered with your site can use their login details to log into other systems.
A standard form is provided with the worker designed to be used via an iCM form shortcut app. This form lets you manage clients (Relying Parties) and create client ID and secret keys for them.
Worker Configuration Properties
| Property | Type | Description |
|---|---|---|
| claimConfig | Object, optional | |
| claimConfig.profileClaimsMapping | Object, optional | This object maps claims to user profile fields. It is only needed if your platform doesn't use our standard user profile object/form, in the format:{See below for more information |
| claimConfig.customProfileClaimsMapping | Array of objects, optional | Used to define custom claims and map them to user profile fields. Each object has three properties:{ |
{
"name": "oauth",
"instances": 1,
"claimConfig": {
"profileClaimsMapping": {...},
"customProfileClaimsMapping": [...]
}
}
Security
The OAuth worker must be assigned to the "OPEN" API Server security key.
Discovery Document
The OAuth worker publishes configuration information in a discovery document, as per the OpenID Connect protocol. It can be found at:
https://[websiteURL]/apiserver/oauth/http/.well-known/openid-configuration
For example:
{
"response_types_supported": ["code", "id_token"],
"scopes_supported": ["openid", "email", "profile", "address", "phone"],
"issuer": "https://demo.gosprd2devweb1.si.lan.gossinteractive.com/apiserver/oauth/http",
"authorization_endpoint": "https://demo.gosprd2devweb1.si.lan.gossinteractive.com/apiserver/oauth/http/auth",
"userinfo_endpoint": "https://demo.gosprd2devweb1.si.lan.gossinteractive.com/apiserver/oauth/http/userinfo",
"token_endpoint_auth_signing_alg_values_supported": ["RS256"],
"claims_supported": ["sub", "name", "family_name", "given_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", "updated_at", "email", "email_verified", "address", "phone_number", "phone_number_verified"],
"end_session": "https://demo.gosprd2devweb1.si.lan.gossinteractive.com/apiserver/oauth/http/logout",
"jwks_uri": "https://demo.gosprd2devweb1.si.lan.gossinteractive.com/apiserver/oauth/http/jwks",
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"],
"token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
"token_endpoint": "https://demo.gosprd2devweb1.si.lan.gossinteractive.com/apiserver/oauth/http/token"
}
The proxying of this resource is handled by the website frameworks (iCM4j version 12.9.8 and iCM.NET version 12.3.22).
If manual configuration is needed, OpenID Connect clients will need to follow the Authorization Code flow with the endpoints:
- /oauth/http/auth
- /oauth/http/token
- /oauth/http/userinfo
- /oauth/http/logout
- /oauth/http/jwks
Supported Claims
If your site is using a standard user profile form, profile fields are mapped to claims as follows:
| Claim | Profile Field |
|---|---|
| name | DISPLAYNAME or UserName if there isn't one |
| family_name | LASTNAME |
| given_name | FIRSTNAME |
| preferred_username | PREFNAME |
| website | URL |
| address | A JSON object where:{ |
| phone_number | TELEPHONE or MOBILE |
Claim Mappings
In the worker configuration, claims can be mapped to user profile fields, overriding the defaults above. This is designed to cater for non-standard profiles, or profiles that use the older nested structure.
If a claim is not included, the defaults in the table above will be used. You can also map a claim as null or an empty string. For example:
"claimConfig": {
"profileClaimsMapping": {
"name": "",
"family_name": "CONTACT.NAME.LASTNAME",
"given_name": "CONTACT.NAME.FIRSTNAME",
"preferred_username": "",
"website": "",
"email": "",
"address": "",
"phone_number": ""
}
}
Custom Claims
The
The list of claims and the user profile fields they map to should be listed here, which will then be returned in the userinfo and token endpoints.
For example, adding this to the custom mapping:
"customProfileClaimsMapping": [{
"claimName": "custom_claim",
"userProfileField": "CUSTOMLASTNAME",
"displayName": "Custom LASTNAME"
}
]
Would update the list of supported claims in the discovery document (note the
"claims_supported": ["sub", "name", "family_name", "given_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", "updated_at", "email", "email_verified", "address", "phone_number", "phone_number_verified", "custom_claim"]
Registering OpenId Connect Clients (Relying Parties)
Relying Parties are the services/clients that want to use iCM as an OpenID Provider. They are registered using the OIDCPCLIENTREGISTRATION form from within iCM - create a form app shortcut and assign it to a suitable iCM user group.
The form allows you to update or delete an existing client by selecting it from the drop-down list and using the corresponding button. It also allows you to register a new client through the corresponding action button:
To register a new client, enter a client id and client secret. These need to be provided to the client, as the client will use them in requests. In addition, a list of regular expressions needs to be entered. A user that is redirected from the client for authentication will only be redirected back to the URL provided in the request if it matches one of these regular expressions. The regular expressions follow the Java syntax, documented at docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html#sum
Updating a client is similar to registering one. Deleting a client requires checking the checkbox in the confirmation screen:
Share this page
