iMIS Power Suite - SSO Premium

OIDC profile data

Create a custom query in order to provide profile information via the /openid/userinfo endpoint (and, optionally, within the ID Token). This query path should be entered into the OIDC Client Apps screen.

Authoring the profile query

The following are tips when authoring the profile query:

  • The base business object should be CsNameUser. Then, join CsContact with the following relationship: When CsNameUser.Id = CsContact.iMIS Id
  • The profile query must filter on the iMIS Username (not the iMIS ID). It should have only one visible prompt, marked required, filtering on CsNameUser.User Id.
    • Other non-prompt filters are fine to add (using AND logic).
  • You may display any columns.
  • Sorting is not necessary, as this query should always only return one result.
  • Always enter column aliases into the Alias field (the standard iMIS column names do not translate correctly into SSO field names).
  • The profile query must always return exactly one result when queried using an iMIS username.
    • The Limit query results setting cannot be used to limit the results. The query must return one result without enabling this option.
  • For dealing with non-numeric fields, add a custom SQL expression into the query to format the results as needed. Do not forget to include the alias. For example, the following expression formats the birthdate in US format (Month/Day/Year):

    • Expression Alias
    ​FORMAT([vBoCsContact].[BirthDate], 'd', 'en-us') birthdate

Sample query

ASI provides a sample query to download as a starting point. It contains a number of out-of-the-box iMIS fields as well as the correct OpenID field names: Sample query zip folder

Sub-Objects

Sub-objects can be created in the resulting JSON profile object if a column alias contains a . character. The first part of the name, before the ., will be parsed as the group name.

For example, if a query returns these fields:

  • nameData.firstName
  • nameData.lastName
  • nameData.middleInitial
  • birthDate
  • address.street
  • address.city
  • address.state
  • address.zip

The resulting JSON object would be created as:

{
    "nameData":
    {
        "firstName": "",
        "lastName": ""        "middleInitial": ""    },
    "birthDate": null,
    "address": 
    {
        "street": "",
        "city": "",
        "state": "",
        "zip": "",
    }
}

Only one nested depth level is supported. The column names can have zero or one dot (.) character, but not more than one. For example:

  • full_address is correct.
  • address.address_line_1 is correct.
  • address.lines.line1 is not correct.

ID token vs. UserInfo endpoint

OpenID has two distinct locations where user-specific data may appear: The ID Token (which is a standard JWT token), and the UserInfo endpoint.

By default, the query results from the Profile query and Role query settings are always available verbatim to the UserInfo endpoint.

It is also possible to include certain fields from the Profile query and insert them directly into the ID Token. In certain cases, this can save a few network calls if only limited information is needed about the user (such as name and email).

To include fields in the ID Token, edit the Client App settings, and enter a comma-separated list of column names that exist in the Profile query into the ID Token Additional Profile Fields field.

Example

This is a standard example of an ID Token from the iMIS SSO:

{
  "sub": "CSmith",
  "jti": "99999999-0000-0000-0000-b5f825fd092a",
  "iat": 1615316931,
  "nbf": 1615316931,
  "exp": 1615318131,
  "iss": "https://sso.example.com/",
  "aud": "99999999-0000-0000-0000-7bebb7de64b5"
}

If the profile query contains the following result after querying on user csmith:

first_name

last_name

join_date

member_type

member_status

email

id

​Chris

Smith

2013-03-06

RM

A

csmith@example.org

10028564

And you enter the following into the ID Token Additional Profile Fields field:

first_name,last_name,email

Then the new ID Token will be issued as:

{
  "sub": "CSmith",
  "jti": "455103e1-febf-41a1-b83c-b5f825fd092a",
  "iat": 1615316931,
  "nbf": 1615316931,
  "exp": 1615318131,
  "iss": "https://sso.example.com/",
  "aud": "94a79400-aa62-490c-bb6f-7bebb7de64b5",
  "first_name": "Chris",
  "last_name": "Smith",
  "email": "csmith@example.org"
}

Warning! If the profile query returns an error for this user, or the profile query is otherwise unable to be queried correctly by iMIS SSO Premium, then iMIS SSO Premium will not be able to issue an ID Token for this user. Therefore, the user will not be signed in, and the user/third party system will receive an error. Always ensure that the profile query is correctly configured and returns results for all users who will be using iMIS SSO Premium.

Reserved Claim Names

The following list of claim names is reserved and cannot be used in the "ID Token Additional Fields" field. Do not set the IQA column names / aliases to any of these values.

  • actort
  • acr
  • amr
  • aud
  • auth_time
  • azp
  • c_hash
  • at_hash
  • exp
  • iat
  • iss
  • jti
  • nameid
  • nonce
  • nbf
  • prn
  • sid
  • sub
  • typ

Alternate username ("sub") values

Some service providers may require an alternate username to identify the user. By default, the username or "sub" value is the iMIS username.

In the Client App settings, staff users can change the iMIS Username Format to be one of:

  • iMIS Username (default)
  • iMIS ID
  • Primary email Address

If you choose one of the alternate usernames (iMIS ID or primary email address), then you cannot also use the Access Restriction / No Access feature. Using both of these features at the same time is not currently supported.

Standard UserInfo fields

It is recommended to use the OpenID Connect registered claim names as the column names when possible. Other column names can be included, as well, but will need to be explicitly supported by any third parties.

Standard Column Names with iMIS Fields

Use the following column names exactly as they appear in this list (case-sensitive). Example iMIS fields which contain the correct data for the standard field name are shown as well.

Columm Name

Description

Recommended iMIS Field

name

Full name, including prefixes and suffixes.

Name.FULL_NAME

given_name

First name.

Name.FIRST_NAME

family_name

Last name.

Name.LAST_NAME

middle_name

Middle name.

Name.MIDDLE_NAME

nickname

Nickname / Informal name.

Name.INFORMAL

picture

Full URL to a profile picture (PNG/JPG) for the user. Must be publicly visible, not behind a login.

Name_Picture.PICTURE_LOGO

email

email address.

Name.EMAIL

address

(Abstract) Address object. See fields below for IQA columns.


address.formatted

Full formatted address.

Name.FULL_ADDRESS

address.street_address

Street address (Address1, Address2, etc).

Name_Address.ADDRESS_1
Name_Address.ADDRESS_2

address.locality

City name.

Name_Address.CITY

address.region

State / Province.

Name_Address.STATE_PROVINCE

address.postal_code

ZIP or Postal Code.

Name_Address.ZIP

address.country

Country.

Name_Address.COUNTRY

phone_number

Phone number. Recommended to use E.164 notation, e.g. +1 (630) 681-1100.

Name.HOME_PHONE

Name.WORK_PHONE

Name_Demo.Mobile_Phone

Name.TOLL_FREE

gender

Gender. Applicable values are (string) male or female.

Name.GENDER

birthdate

Birth date, represented in ISO 8601 format (YYYY-MM-DD).

Name.EMAIL

zoneinfo

Time zone for the user's location. Refer to List of Time Zones, use value from TZ column, e.g. America/Chicago.

N/A

locale

User's preferred locale / language setting, e.g. en-US or fr-CA.

N/A

updated_at

When the user's information was last updated (in UNIX time, seconds since 1970-01-01).

N/A