Okta authentication has been introduced for allowing single sign-on between your Okta and your Storefront. Users that have already logged in Okta will be able to automatically login to your Storefront without entering their credentials.

Setting up Okta STEP 1

To enable the Okta feature in Storefront, please proceed with the following guide:
Go to this link: https://login.okta.com/.

After login in, click on the Applications > Applications sub-option, from the Main menu.

Then click on the "Add Application" button to register an application.

On the following window, choose as “Platform“ the Web option, and then choose for the “Sign on method“ the OpenID Connect radio button.

Continue by clicking on the Create button.

From the next window, enter a name for your application next to the “Application name” text field and you can optionally add an application logo on the next field.

Afterwards, you must provide a dummy URI for the “Login redirect URIs” options, in order to proceed. Click on the “+Add URI“ button and fill in the field with the following URI: “http://localhost“.

Eventually, you can click on the Save button at the bottom of the page in order to proceed. For the “Login redirect URIs” you can leave it as-is and we will get back to it later in this guide.

Once the Save button is clicked, you will be redirected to the application’s Client Credentials & General Settings page. Another way to access this page is by clicking on the application you have just created and then select the General tab.

Here you need to save the following information for later use in BSS:

Client ID: This id will be used in the BSS’s “Client Id” field, located on the Okta Settings page.
Client secret: This secret will be used in the BSS’s “Client Secret” field, located on the Okta Settings page.
Okta domain: This domain will be used in the BSS’s “Authority” field, located on the Okta Settings page.

Then you need to navigate to the Assignments tab, where you will find the Assign button. Click it and then choose to assign the application to certain “Groups” of people or specific “People“ from your organization that you wish to allow access to the Storefront via Okta.

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 > External Authentication (as explained on this Documentation).
Click on the Okta "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 [Okta domain] to the Authority text field (domain: <uniqueDomain>.okta.com).
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	'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 Okta 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 Okta - Continued STEP 3

Now, by going back to the https://login.okta.com/ you can perform the next five easy actions:

Click on the Application > Application sub-menu button and locate the application you have previously created.
Click on it and then click on the Edit button for the General Settings section of this page.
Then paste your stored [Callback Url] to the Login Redirect URIs text field by editing the “dummy URI” you have previously used.
Then, optionally, you can paste your stored [Logout Url] to the Logout Redirect URIs text field by clicking on the “+ Add URI“ button.
Also, make sure that the checkbox option “Authorization Code” is enabled.
Optionally, you can also alter other options such as asking for a user’s consent and more.
Click on the Save 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 back to the BSS Setup > Administration > System Options > External Authentication and click on the Okta "Settings (OIDC)" button.

Click the "Activate" button on the top bar.
Copy the "Authenticate Url" and open a new web-browser tab to paste that URL.
Your web browser will redirect you to Okta login page in order to log in with your Okta credentials.
After a successful login, you will be redirected back to the Storefront and our system will log in/register you.

By clicking on the "Show Authentication" button from the top bar and the External Authentication will from now on be available to the Storefront.
The same button will then display the “Hide Authentication“ in case you wish to hide this External Authentication option from your Storefront.

First Storefront Login with Okta Credentials

After the configuration and activation of the Okta external authentication for Storefront, you can choose to login to Storefront via your Okta credentials.

You can click on the "Okta" button, located under the External Authentication section.

Provide your corresponding credentials on the new Okta login page that you are redirected to.

After a successful login, you are again redirected to our Storefront.

During every first-time login via any external identity provider, the following registration form might appear, depending on the following factors:

For matching Account Codes between the BSS and the identity provider, the registration form will appear with all its fields pre-filled for you to check them and proceed with the log-in or update them and then proceed with the log-in.
Otherwise, if no matching of the Account Codes is found between the BSS and the identity provider, the registration form will appear with all its fields empty for you to fill them in but only if the Advanced Settings checkbox is enabled. Else, the registration form will not appear and the log-in process will stop.

In the event that the registration form appears, it will do so only once, and with it you can:

Either update your pre-existing BSS account as well as your BSS contact,
Or register a BSS account as well as a BSS contact, since the external identity provider does not possess all the required information that our systems need if there is no pre-existing BSS account.

If you have updated your pre-existing BSS account via the registration form as well as accepted the "terms of use" via the dedicated checkbox and clicked on the "Update" button, the Storefront is now fully accessible to you.

If you have registered a BSS account as well as a BSS contact by filling in all the required fields as well as accepting the "terms of use" dedicated checkbox and clicking on the "Update" button, a BSS account and contact are created based on the provided information and the Storefront is now fully accessible to you.

As a result, the account and contact that have been created in our BSS are now connected with the Okta account used to login to the Storefront.

Okta (OIDC)