| Excerpt |
|---|
Azure Active Directory (Azure AD) authentication has been introduced for allowing single sign-on capabilities between your Azure AD and the BSS. Users that have already logged in Azure AD will be able to automatically login to the BSS without entering their credentials. |
| Rw ui textbox macro | ||
|---|---|---|
| ||
Since the following guide contains four main steps with some back-and-forths between our BSS Setup web page and the portal.azure.com web page, we advise you to keep both pages open on different tabs of your web browser. |
Setting up Azure AD
| Status | ||||
|---|---|---|---|---|
|
To enable the Azure AD (OIDC) feature in BSS, please proceed with the following guide:
Go to this link https://portal.azure.com/ and click on the "Azure Active Directory".
Click on "App registrations" option, from the Manage menu.
Then click on the "+ New registration" button to register an application.
On the following window, enter a name for your application under the Name text field. Example: "My Open Id Connect"
| Rw ui textbox macro | ||
|---|---|---|
| ||
Please note that during this configuration of your Azure AD App, the only choice of Supported account types should be the "Accounts in this organizational directory only (Your Company only - Single-tenant)". This option is used when you wish to enable your Azure AD only for your BSS, by only trusting your company's Azure AD. |
After you have chosen the first one of the three Supported account types, you can continue by clicking on the "Register" button.
From the next window, copy and store for later use, the following two IDs:
- "Application (client) ID"
- "Directory (tenant) ID"
Back to the Manage menu, click on the "Certificates & secrets" and create a " + New client secret".
Copy and store, for later use, the "Key Value" that was created.
Setting up the BSS Mechanism Status colour Blue title Step 2
| colour | Blue |
|---|---|
| title | Step 2 |
Now on BSS, go to: BSS Setup > Administration > System Options > BSS Login Settings (as explained on this Documentation).
Click on the "Settings (OIDC)" button.
ID and Secret - Setup
On the following page, you are required to utilize the previously-stored IDs from "Step 1" and paste them to their corresponding fields. More specifically:
- Provide a name to the Instance Name text field.
Paste the following link, along with your stored [Directory (tenant) ID], i.e. "https://login.microsoftonline.com/[Directory (tenant) ID]/v2.0" to the Authority text field.
Rw ui textbox macro type note The Issuer field was changed to the Authority field
Please note that the Authority text field was formerly the Issuer text field. Consequently, if you fill in the Authority field with the [Directory (tenant) ID], you need to leave blank the Issuer field, because it is used only for backward compatibility reasons.
However, the Issuer field can be populated only for Multi-Tenant configurations such as the ones that follow.- Paste your stored [Application (client) ID] to the Client Id text field.
- Paste your stored [Key Value] to the Client Secret text field.
- Then click on the Save button.
| Rw ui textbox macro | ||
|---|---|---|
| ||
Setting up the BSS Mechanism for "Single" Logins To allow the single login for Azure AD, the Authority and the Issuer values must be set to the following values: Accounts in this organizational directory only (Single-tenant): |
Now that you have saved those settings you can copy and store, for later use, the following two URLs:
- The "Callback Url".
- The "Logout Url".
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 (claims), 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.
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.
| Rw ui expands macro | ||||||||
|---|---|---|---|---|---|---|---|---|
|
| View file | ||||
|---|---|---|---|---|
|
| View file | ||||
|---|---|---|---|---|
|
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.
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 URL:
- The "Callback Url".
Setting up of Azure AD - Continued
| Status | ||||
|---|---|---|---|---|
|
Now, by going back to the https://portal.azure.com/ you can perform the next seven easy actions:
- Click on "Azure Active Directory"
- Click on "App registrations" option, from the Manage menu.
- Find the application with name "My Open Id Connect" or any other name that you have assigned to your application during its creation.
- Click on the "Authentication" button and the following page will appear.
- Paste the [Callback Url] to the Redirect URIs > Add URI text field.
- Paste the [Logout Url] to the Logout URL text field.
- Click on "Save".
Testing & Activation
| Status | ||||
|---|---|---|---|---|
|
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 > BSS Login Settings and click on the "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 Azure AD in order to log in with your Azure AD credentials.
- After a successful login, you will be redirected back to the BSS and our system will log in/register you.
By clicking on the "Show in BSS" button from the top bar and the External Authentication will from now on be available to the BSS.
The same button will then display the “Hide from BSS“ in case you wish to hide this External Authentication option from the BSS.
First BSS Login with Azure AD Credentials
After the configuration and activation of the Azure AD external authentication for BSS, you can choose to login via your Azure AD credentials.
You can click on the "Azure AD" button, located under the "---- or ----" section.
Provide your corresponding credentials on the new Azure AD login page that you are redirected to or choose one of your "Microsoft Login" saved accounts.
In the event that your login was not successful, a failure message will appear, as in the following image, indicating the reason.
After a successful login, you are again redirected to the BSS.
As a result, the account and contact that have been created in our BSS are now linked with the Azure AD account used to login to the BSS.
Table of Contents
| Table of Contents | ||
|---|---|---|
|