Configuring OAuth 2 > Auth0
Note: Single Sign-on may not be available in your plan. Please contact your CSM to learn more.
This article will cover how you can configure your OAuth 2 setup in the AdvocateHub using Auth0. This provides your Advocates with a seamless, easy way to enter your hub.
Prerequisite: You need to sign up for an account with Auth0. The free account may be enough for you but check out the packages offered by Auth0 as they may suit your needs.
This article will cover:
Gather information from Auth0
Once you have completed the signup process you should land on your Auth0 Dashboard, click the 'Create Application' button:
Name your Application, select 'Regular Web Application as your Application Type and hit 'Create':
You can skip the technology selection step and move to the next step.
You will be brought to a 'Quick Start' tab but you can ignore this and open the tab next to it, 'Settings':
On the 'Settings' tab you will see a number of fields, some of which are already filled out and some we will have to enter some information in to. At the top of the page in the 'Basic information' section, you should see Client ID and Client Secret, we will need to enter these into the AdvocateHub later:
You can ignore any fields that we do not mention here. Scroll down the page until you reach the field titled 'Allowed Callback URLs'. In here you will need to enter the below URL, replacing 'insert hub domain' with the subdomain or custom domain of your AdvocateHub:
https://{insert hub domain}.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
i.e
After entering this information, continue to scroll down to the bottom of the page where you should see a link title 'Advanced Settings'
Click this link which should reveal another section of information. The tab we are concerned with is 'Endpoints', this contains more of the information we will need to enter into the hub in our next steps:
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:
Here's quick guide of a basic setup as an example:
| Client ID | Paste in the Client ID we retrieved from your Auth0 in the earlier steps above |
| Client Secret | Paste in the Client Secret we retrieved from your Auth0 in the earlier steps above |
| Endpoint | This is the value in the 'Domain' field which you find in the same place as your Client ID and Client Secret above |
| Token URL | /oauth/token |
| Authorize URL | /authorize |
| Fetch User Path | /userinfo |
| Scope | Specify the scope based on your OpenID configuration, supported scopes and supported claims. |
| Ignore OAuth2 State | Leave box unchecked |
| UID Lookup | sub |
| Name Lookup | name |
| Email Lookup | |
| URL Lookup | Leave blank |
| Image Lookup | picture |
Note: If you are using an Auth0 Custom Domain you will use the Custom Domain for each of the Endpoints except the /userinfo endpoint. This one needs to be your regular domain. Read more on this at the Auth0 site - https://auth0.com/docs/custom-domains.
i.e
You can read more about scopes and claims on Auth0 documentation. And you can refer the OpenID configuration endpoint in the 'endpoints' tab in the advanced settings.
Adding users to Auth0
Our setup should be all hooked up now. Now we need to add users to the database we are going to authenticate against, and this is where having a paid package with Auth0 will come into play. There are ways of migrating users to Auth0 and also bulk importing users; please find links to Auth0 documentation that cover these scenarios below:
For testing purposes, you can create users in the User Management page on the left side of the dashboard.
You need to make sure they have been added to the right application to be authorized to access it. You also need to give them a name otherwise, the name field will be populated with the email address.
Create a user and select the connection type.
You can then view the user's details, and assign them specific permissions and access to specific applications.
You can refer to the user's Raw JSON to see how the user's data is scoped (to help with setting the OpenID scope.
Add final cosmetic touches
Auth0 provides us with something they call 'Lock' by default. This is what your Advocates will see when they attempt to login 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 Auth0 does allow you to customize this fairly heavily using JavaScript so you may need a small amount of time from a development resource to achieve your desired results. Check out the Auth0 documentation on this for more details:
https://auth0.com/docs/libraries/lock/lock-ui-customization
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 scroll 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:
Adding additional authentications to your login 'Lock'
As I touched on earlier, Auth0 also allows you to easily attach other 'connections' for your Advocates to login with such as Facebook, Salesforce, Google and many more. These will be added to your 'Lock' and you can customize how these display on your lock as was mentioned above.
Once again, Auth0 provide fantastic documentation on this here - https://auth0.com/docs/identityproviders