Skip to main content
Skip table of contents

OIDC Profile Data

Overview

Create a custom IQA in order to provide profile information via the /openid/userinfo endpoint (and, optionally, within the ID Token).

This IQA query path should be entered into the OIDC Client Apps screen.

Authoring Your Profile IQA

Here are some tips when authoring your Profile IQA.

  • Your base object should be CsNameUser. Then, you can join CsContact with the following relationship: When CsNameUser.Id = CsContact.iMIS Id

  • The profile IQA 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 OK to add (using "AND" logic).

  • You may display any columns you wish.

  • Sorting is not necessary, as this IQA 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 IQA must always return exactly one result, when queried using an iMIS username.

    • You cannot use the "Limit query results" feature to limit the results. The iMIS REST API does not respect this setting. Your IQA must return one result without enabling this option.

  • For dealing with non-numeric fields, you can add a custom SQL expression into the IQA to format the results as needed. Don't forget to include the alias! For example:

    ExpressionAlias
    FORMAT([vBoCsContact].[BirthDate], 'd', 'en-us')birthdate
    Will format the birthdate in U.S. format, ex: 11/26/1985

Sample IQA

CSI provides a sample IQA for you 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 (see below).

Download Sample Profile IQA

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 an IQA 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:

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

Only one nested depth level is supported. Your column names can have zero or one dot (".") character, but not more than one.

  • (tick) full_address

  • (tick) address.address_line_1

  • (error) address.lines.line1

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 IQA and Role IQA settings are always available verbatim to the UserInfo endpoint.

It is also possible to include certain fields from the Profile IQA 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 your Client App settings, and enter a comma-separated list of column names that exist in your Profile IQA into the ID Token Additional Profile Fields field.

Example

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

JSON
{
  "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 your profile IQA 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 your new ID Token will be issued as:

JSON
{
  "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"
}

Profile IQA Query Failures

If the Profile IQA returns an error for this user, or the Profile IQA is otherwise unable to be queried correctly by the Cloud SSO, then the Cloud SSO 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 your profile IQA is correctly configured and returns results for all users who will be using the Cloud SSO.

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 your 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, you can change the iMIS Username Format to be one of:

  • iMIS Username (default)

  • iMIS ID

  • Primary E-mail Address

If you choose one of the alternate usernames (iMIS ID or Primary E-mail 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 your 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

E-mail 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


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.