Implementing OpenID Connect (OIDC)

When OIDC is enabled or in test mode, users are presented with a sign-in screen that only displays an email field.

Figure 1: Staff site view

Figure 2: Public site view

When they enter their email, they are redirected to the OIDC provider to enter their remaining credentials. The external directory verifies their credentials and redirects the user back to iMIS after they have successfully logged in. If the user did not have an iMIS account, one is created for them at this time and the following information is added to iMIS from the OIDC provider:

• First and Last name
• Email address: The email address is also used as their username

Figure 3: System administrator view

System administrators have the option to use their iMIS credentials or OIDC credentials. Staff and public users only have the option to their OIDC credentials.

Review the following before you begin configuring OIDC:

• To avoid disruption for staff users, it is recommended to test and configure OIDC during non-business hours.
• Depending on how OIDC is configured, the Email address field in the Synchronize primary phone numbers and email section (Settings > Contacts > System options) is overruled by the email address used by the external directory:
  • Staff users only: OIDC syncs staff user email addresses from the external directory, while public user email addresses continue to sync according to the Email address setting.
  • Staff and public users: All email addresses synchronization comes from the external directory.
• OIDC cannot be used with multi-factor authentication (MFA). If OIDC is enabled or in test mode, then MFA is automatically disabled. Similarly, if MFA is enabled, then OIDC is disabled.

Note: MFA is still recommended for the external directory sign in.

• When OIDC is enabled, staff users who are not system administrators are unable to access the iMIS Staff site through the API, which means they cannot request a new token from the token endpoint using the password grant_type. System administrators can still receive their token with a password. External SSO applications can still receive staff users’ token and use the refresh_token grant type.
• Before you begin, ensure all iMIS staff users are properly configured with a first and last name in either Entra ID or Okta. After OIDC is enabled, the staff users’ first and last names and email in iMIS are synchronized with the external directory; therefore, the users’ first and last names and email can no longer be updated in iMIS.
• OIDC for public user authentication supports only a single external provider in an all-or-nothing configuration. This means all public users must be authenticated through the chosen external directory, with no option for mixed authentication methods.

Review and complete the following sections before configuring the iMIS OIDC settings.

Ensure each staff user has a first and last name in Entra ID

Each user must have a first and last name in the external directory. This is the name that is synchronized with iMIS after OIDC is enabled. The user’s first and last names cannot be updated in iMIS after OIDC is enabled, since the name is being pulled from the external directory.

Before you begin, ensure all iMIS staff users are properly configured with a first and last name in the Entra ID.

(New apps only) Add a platform

If you created a new app registration, you must populate the Redirect URI:

1. From the navigation, select App registrations then choose the application.
2. From the navigation, select Authentication.
3. Click Add a platform.
4. Click Web.
5. Redirect URIs - Enter the iMIS website (e.g. https://example.imiscloud.com/staff).
6. From-channel logout URL - Enter the iMIS website (e.g. https://example.imiscloud.com/staff).
7. Enable Access tokens (used for implicit flows) and ID tokens (used for implicit flows and hybrid flows).
8. Click Configure.

(Existing Apps only) Ensure Access Tokens & ID tokens are enabled for the application

If you are using an existing app registration and did not create a new one, ensure the application has Access tokens and ID tokens enabled:

1. From the navigation, select App registrations then choose the application.
2. From the navigation, select Authentication.
3. Scroll down to the Implicit grant and hybrid flows section.
4. Enable Access tokens (used for implicit flows) and ID tokens (used for implicit flows and hybrid flows).

Note: These options will not appear if there is no platform defined. See Add a platform.

5. Click Save.

Create a new role & assign the role to users

The iMIS setup requires a Claim value, which is a Role defined in Entra ID. You can use any role, but ASI recommends creating a new role for the iMIS OIDC connection.

Create the app role

Do the following to create the role:

1. From the navigation, select App registrations then choose the application.
2. From the navigation, select App roles.
3. Click Create app role:
   1. Display name - iMIS OIDC Access
   2. Allowed member types - Users/Groups
   3. Value - iMIS_OIDC_Access
   4. Description - Role used for iMIS Open ID Connect
   5. Do you want to enable this app role - Checked
4. Click Apply.

Assigning the role

Do the following to assign the role to the required users or groups:

1. From the navigation, select Enterprise applications then choose the application.

Tip! Make sure you are working in the Enterprise applications navigation and not the App registrations navigation.

2. Select Users and groups.



3. Select the checkbox next to the users and/or groups.
4. Click Edit assignment.
5. Under Select a role, click None Selected.



6. Choose the iMIS OIDC Access role, then click Select.



7. Click Assign.

Adding the Required Claims

Do the following to add the required claims:

1. From the navigation, select App registrations then choose the application.
2. From the navigation, select Token configuration.
3. Click Add optional claim.
4. From the Token type, choose ID.
5. Enable the required tokens:
   • email
   • family_name
   • given_name
   • login_hint(only required if Set login hint is enabled in the iMIS OIDC settings)
   • upn (only required if Set login hint is enabled in the iMIS OIDC settings)
6. Click Add.

Note: Be sure to create claims for System Administrators, regular Staff users, and public users. For more information, see Configure optional claims.

Updating the API permissions

Do the following to add the required API permissions:

1. From the navigation, select App registrations then choose the application.
2. From the navigation, select API permissions.
3. Click Add a permission.
4. Click Microsoft Graph.



5. Click Delegated permissions.



6. Enable the following:
   • email
   • openid
   • profile
   • User.Read.
7. Click Add permissions.

Obtaining the Client ID and Tenant

iMIS requires a Client ID and Tenant from Entra ID. Do the following to obtain these values from Entra ID:

1. From the navigation, select App registrations then choose the application.



2. From Overview, copy the following:
   • Application (client) ID - The Client ID required for the iMIS configuration.
   • Directory (tenant) ID - The Tenant required for the iMIS configuration.

   

3. Paste the values in iMIS or in a safe location where you will have access to them later when you configure iMIS.

Review and complete the following sections before configuring the iMIS OIDC settings.

Creating an Okta application

To create an application, do the following:

1. Click the Admin button to navigate to the developer portal.



2. From the navigation, go to Applications > Applications.
3. Click Create App Integration.
4. From the pop-up window, select OIDC - OpenID Connect, and then select Web Application.



5. Click Next.
6. Enter an App Integration Name. Optionally, upload a Logo.
7. Enable the following settings:
   1. Grant type:
      • Client acting on behalf of itself - Client Credentials
      • Client acting on behalf of a user - Implicit (hybrid)

      Note: The Authorization Code setting is enabled by default.

      

   2. Sign-in redirect URLS:
      • Enter the URL to your iMIS sign-in page, for example https://example/sign-in.org/
8. From the Assignments section, enable Skip group assignment for now.
9. Click Save. Once the app has been created, disable the Allow Access Token with implicit grant type option in the Grant type area of the General tab.
10. Click Save.

Adding users

Each staff user must have a first and last name in the external directory.

Note: Review existing Staff users accounts to ensure they have first and last name fields populated.

To add users to your directory, do the following:

1. From the navigation, go to Directory > People.
2. Click Add person.
3. Enter the required information.



4. Click Save or Save and Add Another to continue adding users.

Adding groups

Groups allow you to differentiate between System administrators (SysAdmins), regular Staff users, and public users. To add a group and assign users, do the following:

1. From the navigation, go to Directory > Groups.
2. Click Add Group.
3. Enter a Name and optional Description, then click Save.
4. Click the name link, then click Assign people.
5. Add your staff users by clicking the plus (+) icon next to their name.
6. Continue adding users, then click Done when you are finished.

Important! Be sure to add separate groups for System Administrators, regular Staff users, and public users.

Adding claims

Claims allow you to add specific identifiers, such as an email address, to access tokens.

Important! In order to use OIDC for both staff and public users, you must have claims for each group.

To add a claim for System administrators, do the following:

1. From the developer portal, go to Security > API.
2. Click the name link of your Authorization server.
3. Go to the Claims tab.



4. Click Add Claim.
5. Enter a unique name.
6. Select ID Token from the Include in token type drop-down.
7. Select Groups from the Value type drop-down.
8. From the Filter drop-down, select Equals, and enter SysAdmin.
9. Click Create.



10. Repeat steps 1-5.
11. Select Access Token from the Include in token type drop-down.
12. Repeat steps 7-9.

To add additional claims for staff and public users, repeat the previous steps, and filter on the corresponding group. Be sure to click Create when you finish configuring each claim. For more information regarding claims, see Add custom claims.

Assigning users to the application

You must add your users to the application for access to be granted to each individual user:

1. From your application, go to the Assignments tab.
2. From the Assign drop-down, click Assign to Groups.
3. Add your Staff users and SysAdmin groups. Alternatively, you can assign individual users using the People button.

Testing the token sent to iMIS

The Okta developer portal allows you to preview the token that is sent to iMIS to ensure that the roles are being sent correctly. For example, to preview the SysAdmin token, do the folowing:

1. From the developer portal, go to Security > API.
2. Click the name link of your Authorization server.
3. Go to the Token Preview tab.
4. Enter your OAuth/OIDC client name. This is the name of your application.
5. Select Implicit (hybrid) from the Grant type drop-down.
6. Enter a User.
7. Select id_token from the Response type drop-down.
8. From the Scopes field, enter the following:
   • openid
   • profile
   • email
9. Click Preview Token.

iMIS prerequisites

Before configuring OIDC, confirm the following are configured in iMIS:

• Ensure the OpenID Connect license appears in Settings > About iMIS. If you do not see the license, contact ASI Technical Support.
• OIDC does not update the staff user’s iMIS username and instead uses their email address. Verify staff users have their OIDC email address on their iMIS account page.
Click to view image



• To use the website with OIDC, the site Access settings must be set to All Staff Full Control.
Click to view image

Configuring OIDC

You must be a system administrator to configure OIDC.

Entra ID

(new image)

Okta

Do the following to configure iMIS with your external directory:

1. Go to Settings > Contacts > Open ID Connect.
2. Select one of the following OIDC authentication options:

   Note: To avoid disruption for staff users, it is recommended to test and configure OIDC during non-business hours.

   • Disabled – Select to disable OIDC. When selected, users can only log in with their iMIS credentials.
   • Test mode – Select when testing the connection with iMIS and the external directory. When selected, staff users can sign in with their iMIS or external directory credentials.
   • Enabled – Select to enable the external directory. When selected, the external directory is the only sign in option for staff users. System administrators can still sign in with their iMIS credentials.
3. Enter the Authentication service:

   Note: Some of the Authentication service values are in your organization’s external directory portal (such as, Azure portal). You must have access to the specific tenant to find these values. See the Microsoft Documentation for more information.

   1. Type – Select your directory provider. Currently, Entra ID and Okta are supported.
   2. Name – Enter the Name of your external directory; for example, ASI OpenID Connect. This can be any name, as it currently does not appear anywhere.
   3. Client ID – The Client ID assigned to your app. For Entra ID users, this is the Application (client) ID. For Okta users, this is the Client ID.
   4. (Okta only) Client Secret - The Client Secret is located on the General tab of your Application.
   5. (Okta only) Well-Known URL - This is the Metadata URI located on the Settings tab of the default Authorization Server. See below for more information.
   6. (Entra ID only) Tenant - The Tenant assigned to your app is the Directory (tenant) ID.
   7. Authority URL:

      • Entra ID - Enter https://login.microsoftonline.com/<tenant>/, where <tenant> is the string entered in the Tenant field.

      There are common authority URLs defined in the Microsoft Documentation.

      Example: https://login.microsoftonline.com/ae2d240f-abc1-def2-ghi3-jklmnop45678

      • Okta - The Authority URL is the Okta URL that is used for authentication with iMIS:
        1. From the Okta developer portal, go to Security > API.
        2. From the Authorization Servers tab, click the default link. This is the server generated by Okta.
        3. From the Settings tab, locate the Metadata URI and Issuer fields. The Metadata URI is the Well-Known URL field in your iMIS OIDC configuration. The Issuer (or Okta URL) is your Authority URL in your iMIS OIDC configuration.
   8. External Claim ID - When set, this custom claim enables you to assign a unique identifier to users that is not their email address. The value entered in this field must correspond to your active directory configuration. See Configure optional claims for Entra ID, and Add custom claims for Okta.
   9. Redirect login URL – The redirect URL of your app, where authentication responses can be sent and received by your app. A redirect URI is the location where the authorization server sends the user once the app has been successfully authorized and granted an authorization code or access token. For many users, this will be their iMIS URL, such as https://example.imiscloud.com/. This URL must match exactly with the Redirect URI defined in your external directory. More information about the Redirect URI is in the Microsoft Documentation.
   10. Set login hint – When enabled, the staff user only needs to enter their email address in iMIS. When they are redirected to the OIDC provider, their email address is automatically populated in the OIDC authentication interface.
4. In the User autentication section, define the claim information that is used to verify that a user authenticated by the identify provider is a staff user:
   • Require OIDC for - Select Staff Only or Staff & Public Users to restrict OIDC logins for specific users. If Staff & Public Users is selected, all users are authenticated by the external provider, with no exception.

   Note: When Staff Only is enabled, OIDC syncs staff user email addresses from the external directory, while public user email addresses continue to sync according to the Email address setting. If Staff & Public Users is enabled, all synchronization comes from the external directory.

   • Entra ID:
     • Claim type - The URI (Claim type) for the associated Claim value. The instructions above use the app Role as the Claim value, so the Claim type URI is the following: http://schemas.microsoft.com/ws/2008/06/identity/claims/role

     Important! If you are not using the app Role to verify the user's authentication, you must review the Microsoft list of claim types to determine which claim type URI is right for you. It is important that the URI is copied exactly as it appears in the Microsoft list of claim types. The URI must begin with http and cannot begin with https.

     • Claim value - Enter the Value of the app role you created. The instructions above suggested the following value: iMIS_OIDC_Access

     Note: See the Microsoft Documentation for more information about custom claims.

   • Okta: 
     • Claim type - This field is not required for Okta configuration but is required to have a value. Enter http://schemas.microsoft.com/ws/2008/06/identity/claims/role to populate the field. For more information on Okta claims, see the Okta documentation.
     • Claim value - Enter SysAdmin.
5. Under the Forgot username or password email section, enter the Email body that is sent to a staff user when they use the Forgot my username or Forgot my password forms in a website other than the Staff site. It is important that the Email body indicates that the staff user must sign in to iMIS using the Staff site with a link to your organization’s Staff site.
6. Click Save. If the OIDC authentication is set to Enabled, a confirmation displays after clicking Save. You must confirm that signing in with a standard iMIS username and password will no longer work for the specified user types, except for system administrators.

Any activity through the OIDC service is logged and only available to system administrators. The logs contain detailed information about requests that are sent or received through the service or any error messages.

Do the following to review the OIDC logs:

1. Go to Settings > Contacts > Open ID Connect.
2. Click the Logs tab.
3. Use the Level drop-down to filter the logs based on the type of message.
4. Use the Message contains field to filter the logs based on a part of a message.
5. Use the Occurred between fields to filter the logs based on the date the log occurred.
6. Click Find.

Use the following troubleshooting tips while configuring OIDC.

Cannot log into the Staff site

If you've enabled OpenID Connect and can no longer log into the Staff site, do the following:

1. Navigate to a RiSE website that is not the Staff site, such as a public member site.
2. Log into that site.
3. Once logged in, update the URL to the staff site URL.

You should now have access to the Staff site.

Error messages

Error message	Try this
Error: response_type id_token is not enabled for the application	Ensure the Access tokens and ID tokens are enabled on the application.
Is not a staff user in the OpenID provider, according to the staff claim configured in the settings.	Ensure the role is properly assigned to the users and groups.