auth0 (OIDC)
auth0 authentication has been introduced for allowing single sign-on between your auth0 and your Storefront. Users that have already logged in auth0 will be able to automatically login to your Storefront without entering their credentials.
Setting up auth0 STEP 1
To enable the auth0 feature in Storefront, please proceed with the following guide:
Go to this link: https://bit.ly/34nFpgQ
After login in, click on the Applications > Applications sub-option, from the Main menu.
Then click on the "+ Create Application" button to register an application.
On the following pop-up window, choose as “Platform“ the Regular Web Applications option.
Continue by clicking on the Create button.
From the next page that loads, navigate to the Settings tab, where the application’s general settings exist.
Here you need to save the following information for later use in BSS:
Domain: This domain will be used in the BSS’s “Authority” field, located on the auth0 Settings page.
Client ID: This id will be used in the BSS’s “Client Id” field, located on the auth0 Settings page.
Client secret: This secret will be used in the BSS’s “Client Secret” field, located on the auth0 Settings page.
Then scroll down where the “Application Properties” section appears. In this section, the option named “Token Endpoint Authentication Method“ must be Basic.
Afterwards, by scrolling further down, you can see the “Application URIs” section. Here, you must provide a dummy URL for the “Allowed Callback URLs” options, in order to proceed. Click on the respective field and fill in the following URL: “http://localhost“.
Eventually, you can click on the Save Changes button at the bottom of the page in order to proceed. For the “Allowed Callback URLs” you can leave it as-is and we will get back to it later in this guide.
Once the “Save Changes” button is clicked, you can navigate to the User Management > Users sub-option, from the Main menu, where you will find the “+ Create User” button. Click it and then create your users. Then by going to the User Management > Roles sub-option, from the Main menu, you can create certain rules and then assign them to the previously created users for your organization that you wish to allow access to the Storefront via auth0.
After finishing and Saving the assignment(s), the application is now partially ready and a few steps remain, which are analyzed later in this guide.
Setting up the BSS Mechanism STEP 2
Now on BSS, go to: BSS Setup > Administration > System Options > Storefront Login Settings (as explained on this Documentation).
Click on the auth0 "Settings (OIDC)" button.
ID and Secret - Setup
On the following page, you are required to utilize the previously-stored IDs from the "Step 1" section and paste them into their corresponding fields. More specifically:
Provide a name to the Instance Name text field.
Paste your stored [auth0 domain] to the Authority text field (domain: https://<uniqueDomain>.eu.auth0.com). The part of the domain “.eu.“ has 4 values in total depending on the country you choose (Europe=”eu”, Japan=”ja”, Australia=au, etc.).
Paste your stored [Client ID] to the Client Id text field.
Paste your stored [Client Secret] to the Client Secret text field.
Attribute Mapping - Setup
Concerning the Attribute Mapping section of this page, it is introduced as an easy way to map the JSON response of the identity provider to a Property of the BSS Account/Contact/User.
Next to the first five attribute-mapping fields, there is a question mark icon, that upon hovering over it, it displays the default mapping values for your aid.
You don't need to fill in the Attribute Mapping text fields, since the attributes "ExternalId", "First Name", "Last Name", "Email", and "Phone" already have the default mapping, which you can witness below.
Field | Value |
---|---|
ExternalId | 'sub' |
First Name | 'given_name' or 'name' if empty |
Last Name | 'family_name' |
'email' or 'preferredUsername' if empty | |
Phone | 'phone_number' |
Company Name |
|
Country Code |
|
However, if you wish to alter the default mapping, you can do so with either of the two JSON response objects namely IdToken, UserInfo that are utilized for the attribute mapping and the attribute matching.
Please also note that many Attribute Mapping fields can be declared with a comma "," and the priority with which they are written applies (if no value is found in the first, the code checks the second).
Below you will find the two aforementioned JSON files that can be used as an example.
As it is evident from the JSON files, any extra parameter set at the OIDC provider can be placed within the ExtraParameters.
For example, if you want to set the Company Name based on the value of the "cp1" field, then as mapping you must set "IdToken.ExtraParameters.extension_cp_gan". The same logic applies to any other extra parameters that are needed.
Attribute Matching - Setup
Concerning the Attribute Matching section of this page, it is one of the most important functionalities during the registration process, because after filling in the Account Code field, there will be a check via the identity provider's response on whether an account exists under the auth0 Portal with that specific account code, or not. If a match is found between a BSS account and an identity provider's account, then there will be no need for registration on our systems. However, if no match is found, then the registration on our systems is required.
Advanced Settings - Setup
Concerning the Advanced Settings section of this page, it is the most important option during the registration process, because this checkbox, if enabled, can allow the BSS registration process to be initiated in the event that a matching account(based on the "Account Code" entered in the previous section) has not been found during the check between the BSS and the identity provider. In its default disabled state, the checkbox will not allow the BSS registration process to be initiated, and the authentication will not proceed.
Saving Configured Changes
After you have finished with this page's configuration, you must click on the "Save" button.
Now that you have saved all those aforementioned settings of this page, you can copy and store, for later use, the following URIs:
The “Callback Url“.
The “Logout Url“.
Setting up auth0 - Continued STEP 3
Now, by going back to the https://bit.ly/34nFpgQ you can perform the next five easy actions:
Click on the Applications > Applications sub-menu button and locate the application you have previously created.
Click on it and then click on the Settings tab for the Basic Information section to appear.
Afterwards, scroll down and locate the “Application URIs” section.
Then paste your stored [Callback Url] to the “Allowed Callback URLs” text field by deleting the “dummy URI” you have previously used.
Then, optionally, you can paste your stored [Logout Url] to the “Allowed Logout URLs” text field.
Lastly, click on the Save Changes button to save all the changes.
Testing & Activation STEP 4
The final steps of the initialization of the External Authentication feature, require you to once more go