Skip to main content

Setting up a generic OAuth login method

Distributor steps for setting up single sign-on with a generic OAuth2 provider in Encompass: register the redirect URL, then add an OAuth Settings record with app ID, secret and URLs. Requires v24.11+.

B
Written by Bailey Naas-Thornton

Minimum Version Required: 24.11

Pre-Conditions

Your OAuth provider must meet the OAuth2 protocol.


The provider must support including these items in the response:

  • User ID Identifier
    ​
    ​

  • Email Identifier
    ​
    ​

  • Name Identifier

Steps

Before starting in Encompass, the OAuth integration must be setup in the 3rd party OAuth provider.

  • Typically the 'type' in the 3rd party provider will need to be set to 'Web Application'.

The following information will be needed in the setup of the 3rd party provider:

Contact your 3rd party OAuth provider for additional details about how to set up an Application for OAuth in their environment.

You will need the following information out of the 3rd party OAuth provider system to be entered in Encompass in the below steps:

  • App ID
    ​
    ​

  • App Secret
    ​
    ​

  • Request URL
    ​
    ​

  • Authorization URL
    ​
    ​

  • Token URL
    ​
    ​

  • Response UserID Identifier
    ​
    ​

  • Response Email Identifier
    ​
    ​

  • Response Name Identifier
    ​
    ​

  • Scope

After the application is setup in the 3rd party OAuth provider, in Encompass:

  1. Go to the OAuth Settings table
    ​
    ​

  2. Click Add OAuth Settings at the top to add a new record
    ​
    ​

  3. Select Generic as the service provider
    ​
    ​

  4. Fill in the App ID and Client Secret from the 3rd party application
    ​
    ​

  5. Fill in the Request URL, Authorization URL, and Token URL from the 3rd party application
    ​
    ​

  6. Leave Auto Verify Email turned on - This would only be turned off if you want to enforce your users to verify their own email address manually in Encompass. This is typically done when the OAuth provider does not do this automatically.
    ​
    ​

  7. Populate the Response UserID Identifier, Response Email Identifier, and Response Name Identifier with the names of what these values will be in the JWT from the 3rd party provider.
    ​
    ​

  8. Populate the Scope with whatever is required by the 3rd party provider to obtain the UserID, Email, and Name information in Step 7
    ​
    ​

  9. Populate the Icon URL with an image URL that should be displayed on the login page for users to click for the OAuth sign-in method. It is recommended that this is png image, square (equal height and width), between 30x30px and 100x100px in size.
    ​
    ​

  10. Populate the Display Name with the name of the 3rd Party application, this will be displayed in a few places, such as the profile page, as the sign-in method.

Other optional settings, as needed for certain providers:

  • Token Type: Can be set to 'AccessToken' for if the provider uses an AccessToken (instead of the default ID token) for JWT decoding
    ​
    ​

  • Token Post Data: Extra URL values that need to be included in the HTTP request
    ​
    ​

  • LogOut URL: Extra URL to call on the OAuth provider when the user logs out

Best Practices

  • After setup, fully test the OAuth login flow with a sample user before turning on any OAuth requirements (Roles - Require OAuth Login setting)
    ​
    ​

  • Ensure email is matching between Encompass and the 3rd party OAuth system, this is the primary linking mechanism for Encompass.

Did this answer your question?