Configuring OAuth 2 > Okta
This article will cover how you can configure your OAuth 2 setup in the AdvocateHub using Okta. This provides your Advocates with a seamless, easy way to enter your hub.
Prerequisite: You need to sign up for an account with Okta. The free Developer account may be enough for you but check out the packages offered by OKTA as they may suit your needs.
Gather information from Okta
- Sign in to your Okta organization as a user with administrative privileges. Create an org for free (opens new window).
- In the Admin Console, go to Applications > Applications.
- Click Create App Integration.
- On the Create a new app integration page, select OIDC - OpenID Connect as the Sign-in method. Choose an Application type - Creating a web.
- Enter a name for your app integration.
- In the Sign-in redirect URIs box, specify the callback location as https://{{yourhubdomain}}.influitive.com/users/auth/custom_oauth2/callback.
If you have set up a custom domain in Influitive Hub, please insert https://{insert hub custom domain}/users/auth/custom_oauth2/callback
Signout Redirect URLs - After the Advocatehub app contacts Okta to close the user session, Okta redirects the user to one of these URIs. If left blank then the user will be taken to the Advocatehub Sign_in screen. - Click Done. The settings page for the app integration appears, showing the General tab. Make note of the Client ID listed in the Client Credentials section at the bottom of the page since you will need to paste this into the AdvocateHub.
For the detailed info on the above settings please refer to this article - OKTA Oauth Implementation.
Configuration in AdvocateHub
At this point, we need to go back to your AdvocateHub and essentially just plug in some information that I will outline below. Find our OAuth integration under Integrations > Custom OAuth Provider and open the Setup tab, you should see a list of empty fields like this:
Let's fill out this information:
| Client ID | Paste in the Client ID we retrieved from your OKTA in the earlier steps. |
| Client Secret | Paste in the Client Secret we retrieved from your OKTA in the earlier steps. |
| Endpoint | This is the value in the 'Okta Domain' field which you find in the same place as your Client ID and Client Secret |
| Token URL | https://${yourOktaDomain}/oauth2/v1/token. For more info, check this article on: /token endpoint. |
| Authorize URL | https://${yourOktaDomain}/oauth2/v1/authorize. For more info, check this article on: /authorize endpoint. |
| Fetch User Path | https://${yourOktaDomain}/oauth2/v1/userinfo. For more info, check this article on: /userinfo endpoint. |
| Scope | Scopes specify what access privileges are being requested as part of the authorization. For OKTA, an openid scope is required for authentications. You will also need to input the email scope to gain access to the user's email address.  |
| Ignore OAuth2 State | Leave box unchecked |
| UID Lookup | id |
| Name Lookup | displayName |
| Email Lookup | |
| URL Lookup | Leave blank |
| Image Lookup | Leave blank |
Note: If you are using an Okta Custom Domain you will use the Custom Domain for each of the Endpoints.
Adding Users to Okta
The setup is all done now. Now we need to add users to the database we are going to authenticate against. You can follow this article to manage users. The article briefly covers how to add users manually or import them, assign/unassign their applications, and much more.
Adding final Cosmetic touches
This is what your Advocates will see when they attempt to log in if you are using Custom OAuth Single Sign-On, it is where they enter their credentials or can choose other methods of sign up which we will touch on in the next section. It looks like this
The good news is that you can customize the Okta sign_in page using some stylesheets and Javascript. Please check this article on that.
If you are using the dual login aspect of Custom Oauth then you may also want to update the image you use for the Custom Oauth Button that Advocates will see before they get to the 'Lock' we talked about above. You change this image by navigating to Integrations > Custom Oauth Provider > Setup Tab and scrolling to the bottom where you will be given the opportunity to upload an image for the login button and for your icon. By default, we use the below
For context on what this looks like from the Advocates side, here is their view when they navigate to the hub
