OAuth 2.0 Configuration in Nectari

 

Creating a Provider

1. Go to the Administration menu at the top-right

2. Click on the Security menu

3. Click on Authentication in the menu list

4. Click on the + icon, this will add a new item under the list Providers and provide an empty form to configure a new OAuth provider.

   There will be two tabs: General and Users available for each provider.

   • General: This tab is where the required parameters to setup the provider will be saved. Follow the section Setup OAuth 2.0 Provider Parameters.
     

   • Users: This tab is where it is defined which users will be able to login into the Web Client using the specific provider. It will also be where the mapping between the Web Client user and the OAuth provider user is set.
     Follow the section Linking Users to an OAuth 2.0Provider.

Setup OAuth 2.0 Provider Parameters

The following table describes what each of the parameters are and what is expected for them.

It is recommended that the Web Client has been registered with the chosen OAuth provider to be able to obtain the required information. Follow the steps under Creating an OAuth 2.0 Client.

Configuration Parameters
Activate	The toggle button defines whether the OAuth provider should be available for the users to log in from the Login page. When this is set to true, a new button will be displayed under the External Accounts on the Login page.
Description	This is the text that will be displayed for the button that will be shown for the created provider on the Login page. By default, it is set as New Provider and it is recommended that the text is changed for a label that is meaningful for the users when they go on the Login page.
Client ID	The unique public identifier provided by the authorization server needs to be set in the provided text box.
Client Secret	The unique secret string that is only suppose to be known by the Web Client and the authorization server will be set for this text box. The value set is secretive and therefore the text will be hidden after setting it.
Discovery Endpoint	This endpoint is optional in the configuration screen. The intention of the endpoint is to automatically populate the other required endpoints by retrieving the information from the available metadata. If the Discovery endpoint is set, then using the button Discover will populate the values for Authorization Endpoint , Token Endpoint and User Info Endpoint. Dropdowns will be accessible for Scopes with the available scopes by the OAuth provider. Also, the User Identifier will contain a dropdown with available claims that can be used. Ideally, this endpoint is available via /.well-known/openid-configuration.
Authorization Endpoint	The value set for this parameter will be the first endpoint that users will go to authenticate themselves for the OAuth provider and also give permission for the provider to give Web Client limited information. Ideally, this endpoint is available via /authorize.
Token Endpoint	The value set for this parameter will be used to get the Access Token that will be used to get the user's information. Ideally, this endpoint is available via /token.
Scopes	The values will be used to define the permissions to be given to Web Client. The permission given should be enough to be able to get user's information to do the user mapping. Typically, the scopes needed would be openid, email, offline_access, however each provider may have different available scopes. For example, by default, offline_access is added under the scopes, however if it is not an available scope then this should be removed.
Redirect URLs	The URLs defined for the Web Client and Excel Add In are needed to be saved in the authentication server. If the authentication server needs to be redirected to another url then this needs to be changed in this text. For Excel Add In, the port number defined will need to be one that is available on the local machine where the Excel Add In is installed.
User Info Endpoint	The endpoint is used to retrieve the information regarding the user logging in. The information returned will be used to log into Web Client. Ideally, this endpoint is available via /userinfo.
User Identifier	The textbox represents the claim which will be used to retrieve the value for, so that it can be mapped to a value within Web Client user. For example, if the User Identifier is set as "email". Then from the result of the User Info Endpoint, it will search for the parameter "email" and use that value to compare and map the Web Client user.

Linking Users to an OAuth 2.0 Provider

When the General tab is saved for the new provider, the Users tab will be enabled. This is where the users are given the possibility to use the newly created OAuth provider and where the mapping between the Web Client and the provider is made. In other words, a user will not be able to log in to the Web Client using the provider if :

• They are not listed within the grid then they will not be able to login using the Web Client

• The value set for the mapping is not correctly set for the specific user

In the Users Tab, the view contains:

• Grid to view the users that have already been added

• Add icon to add more users to give them the possibility to use the provider

• Delete icon to delete any of the existing users from the list

The following table describes the columns that are displayed in the Grid.

Parameters
Username	This column represents the Web Client user's username that is used to log in.
Name	This column represents the Web Client user's name associated to the username.
Email	This column represents the Web Client user's email associated to the username.
User identifier	The only editable column which represents the value that will be expected to be returned by the OAuth provider for the specified User Identifier claim. For example, If the claim specified under the General Tab for User Identifier is email, then this column should specify the user's email associated to the provider.

Logging In with OAuth 2.0 in Nectari

After the configuration of the OAuth provider is completed, if a provider has been activated then, on the Login page, users will see two sections External Accounts and Basic Authentication.

Basic Authentication:

The Basic Authentication will be used when the user would like to log in with their normal username and password or with a specified Domain.

External Accounts:

If there are OAuth providers active and/or SAML 2.0 has been configured, then the users will be directed to a Login page with buttons for each SSO that are configured.

It is to be noted that the button to log in with SAML 2.0 will only appear for the first central point in the list.

Logging in with OAuth 2.0 in the Excel Add-in

With the configuration done in the Web Client, the users also have the possibility to log into Excel Add-in using the OAuth providers.

On the Login popup of Excel Add-in, there are two radio buttons available: Basic Authentication and External Accounts.

Basic Authentication:

When the Basic Authentication option is selected, the user will be able to log in with their normal username and password or with a specified Domain.

External Accounts:

For the selected central point, if the External Accounts is selected then in the dropdown, it will display all of the available SSO that the user can log in.

It is to be noted that signing into SAML 2.0 will only appear for the central point that it was configured for.