Configuring SAML SSO: Microsoft Azure

Integrating your company's Single Sign-On (SSO) solution with the FCSky platform offers a convenient and secure way for all employees to access the platform. By integrating with the popular identity provider (IdP) Microsoft Azure for SSO, you can enable employees to authenticate into your FCSky platform using their existing company credentials. Follow these instructions to configure the integration with Microsoft Azure.

Prerequisites

  • Admin access to FCSky platform
  • Admin access to cloud-based Azure Active Directory (Azure AD)
  • ‘Application Administrator’ administrative role assigned (Azure AD)
  • Admin access to on-premises Active Directory Users and Computers (Local AD)

FCSky Configuration (Part 1 of 2)

Create a SAML Service Provider

1. Log into your FCSky platform

2. Click on the (admin) settings 'cog' icon (top right)

3. Scroll down to the Configuration → Single Sign On section, then click on the "Configure Single Sign-On from other websites" option

4. Click on the "Add New SAML Service Provider" button

5. Under the 'Authentication Type' field, select the "Service Provider Initiated (SP-Init)" option

6. Copy the value under the 'Assertion Consumer Service (ACS) URL' field (e.g., https://<YourPlatformUrl>/fc/saml/acs/McKJPeVcGExi98J/)

Important: Keep this information handy, as they will be required in later steps.

Open a new tab/window and proceed to the next steps. However, leave this page open, as there's still more to configure.

Azure AD Configuration (Part 1 of 2)

Create an Application

1. Log into your Azure AD portal: https://entra.microsoft.com

2. Go to Applications → Enterprise applications

3. Click on the “New application” button

4. Click on the “Create your own application” button

5. Enter a (unique) name for the app + select the “Integrate any other application you don't find in the gallery (Non-gallery)” option, then click on the “Create” button

Tip: For the purposes of this article, we have used ‘FCSky Platform SSO’ as the name. However, we recommend using a name that is unique/specific to your FCSky platform.

Configure SAML SSO

1. Go to Manage → Single sign-on

2. Click on the “SAML” method

3. In the “Basic SAML Configuration” section, click on the “Edit” button

4. Complete the following details (below), then click on the “Save” button:

  • Identifier (Entity ID)
    • Click on the “Add identifier” link
    • In the text field, enter: https://<YourPlatformUrl>/fc/
  • Reply URL (Assertion Consumer Service URL)
    • Click on the “Add reply URL” link
    • In the text field, paste the 'Assertion Consumer Service (ACS) URL' value you copied from the previous steps (e.g., https://<YourPlatformUrl>/fc/saml/acs/McKJPeVcGExi98J)

SAML Certificates

1. Under the ‘SAML Certificates’ section, action the following (below):

  • Under the ‘Certificate (Base64)’ field, click on the “Download” link

Set up <Enterprise App Name> SSO

1. Under the ‘Set up Enterprise App Name SSO’ section, action the following (below):

  • Copy the value under the ‘Login URL’ field (by clicking on the copy 'double page' icon)
  • Copy the value under the ‘Azure AD Identifier’ field (by clicking on the copy 'double page' icon)

Important: Keep this information handy, as they will be required in later steps.

Return to your FCSky platform tab/window and proceed to the next steps. However, leave this page open, as there's still more to configure.

FCSky Configuration (Part 2 of 2)

Create a SAML Service Provider (cont.)

1. Under the 'Name' field, enter a (unique) name for the app

Tip: For the purposes of this article, we have used ‘Azure AD SSO’ as the name. However, we recommend using a name that is unique/specific to your FCSky platform.

2. Under the 'Identity Provider Single Sign-On URL' field, paste the 'Login URL' value you copied from the previous steps

3. Under the 'Identity Provider Logout/Redirect URL' field, paste the 'Azure AD Identifier' value you copied from the previous steps

4. Under the 'Protocol Binding for SAML Request' field, select the "HTTP-POST" option

5. Under the 'Request Lack Time (In Minutes)' field, select a value (as applicable to your environment/requirement)

6. Under the 'X.509 Signing Identity Provider Certificate' option, upload the 'Certificate (Base64)' file you downloaded from the previous steps

7. Under the 'Is Default SAML SSO?' field, choose whether or not you want SSO login to be the default/only method for accessing your FCSky platform

Tip: Leave this option unchecked to also allow native login, using FCSky platform credentials.

8. Under the 'Is Provision User?', choose whether or not accounts can be created when logging in via SSO (e.g., if a user does not already exist)

Once finished, you should be left with something like this:

9. Click on the "Continue" button

SAML Attributes

This tab contains a list of attributes for mapping fields between FCSky and Azure AD - both mandatory and optional. Whilst you are able to rename these attributes, for the purpose of this article, we will be keeping the default names.

Open a new tab/window and proceed to the next steps. However, leave this page open, as you will need to refer back to it later.

Create SAML Groups

1. Go to your FCSky platform

2. Click on the (admin) settings 'cog' icon (top right)

3. Under the Users section, click on the "SAML Groups" option

4. Click on the "Add SAML Group" button

5. Under the 'Group Name' field, enter a (unique) name for the SAML group

6. Under the 'User Type' field, select the option that is most applicable to the group you are creating, as below:

FC User Type WM Role Type
Corporate World Manager
Division National Manager
Regional Area Manager
Corporate

General Manager

Store Manager

Employee

7. Click on the "Save" button

8. Repeat steps 4-7 for any/all SAML Groups you require

9. Once done, return to your Azure AD portal tab/window and proceed to the next set of steps

Azure AD Configuration (Part 2 of 2)

Attributes & Claims

Important: If you changed any of the SAML attribute names within your FCSky platform, then please ensure you amend the below-mentioned claim names to be an exact match for your environment.

1. In the “Attributes & Claims” section, click on the “Edit” button

2. Action the following (below) to the existing claims that are auto-generated:

  • emailaddress
    • Click on this claim (to edit)
    • In the ‘Name’ field, replace the current value with EmailID
    • In the ‘Namespace’ field, delete the current value
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, leave the current value (user.mail)
  • givenname
    • Click on this claim (to edit)
    • In the ‘Name’ field, replace the current value with FirstName
    • In the ‘Namespace’ field, delete the current value
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, leave the current value (user.givenname)
  • name
    • Click on the 3-dot menu, then click on the “Delete” option
    • In the confirmation prompt that appears, click on the “OK” button
  • surname
    • Click on this claim (to edit)
    • In the ‘Name’ field, replace the current value with LastName
    • In the ‘Namespace’ field, delete the current value
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, leave the current value (user.surname)

If amended correctly, you should be left with something like this:

3. Action the following (below) to create new (additional) claims - based on (at least) all of the mandatory/required fields that appear in the 'SAML Attributes' tab of the SAML connector you configured within your FCSky platform.:

  • Login ID/Username
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter LoginIDUsername
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select an applicable attribute value (e.g., user.employeeid)

Tip: You can use any available attribute for the Login ID value, which will become the account's username. This will be used as the 'identifier' between both systems.

  • Group Name
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter GroupName
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select an applicable attribute value (e.g., user.jobtitle)

Tip: You can use any available attribute for the Group Name value, as long as it is an exact match of a SAML group name within your FCSky platform (found under Settings → Users → SAML Groups).

  • Country
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter Country
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source’ field, select the "Transformation" option, then complete as below:
      • Transformation: Select the "RegexReplace()" option
      • Parameter 1: Select the "Attribute" option
      • Attribute name: Select the user.country option
      • Regex pattern: Enter AU
      • Replacement pattern: Enter Australia

Important: By default, the user.country value from Azure AD gets abbreviated to the country code - e.g., Australia will become AU. This will cause a validation error, as the FCSky platform expects the full country name. Hence the reason we used "Transformation" as the 'Source' for this particular claim.

Note: The above instructions are to replace the country code for Australia specifically. So, you will need to amend the (transformation) field values, based on your applicable country/countries.

  • State
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter State
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select the user.state value

Important: If you are using abbreviations for the state value in Azure AD, this will cause a validation error, as the FCSky platform expects the full state name. So, please ensure you enter the full state name for Azure AD users.

  • City
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter City
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select the user.city value
  • Phone1
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter Phone1
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select the user.telephonenumber (or user.mobilephone) value
  • Language
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter Language
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select the user.preferredlanguage value
  • Area / Region
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter AreaRegion
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select one of the extension attribute values

Important: This value is only required for Area/Regional users (e.g., within the 'Area Manager' Role).

Tip: You can use any available attribute for the Area / Region value, as long as it is an exact match of an Area/Region name within your FCSky platform (found under Settings → Area / Region Management → Manage Area / Region).

  • Franchise User Type
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter FranchiseUserType
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select one of the extension attribute values

Important: This value is only required for Location users (e.g., within the 'General Manager', 'Store Manager' and 'Employee' Roles).

Tip: The only accepted values for the Franchise User Type attribute are "Owner" or "Employee".

  • Franchise ID/Location Name
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter FranchiseIDLocationName
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select one of the extension attribute values

Important: This value is only required for Location & Hierarchy users (e.g., within the 'General Manager', 'Store Manager' and 'Employee' Roles).

Tip: You can use any available attribute for the Franchise ID/Location Name value, as long as it is an exact match of a Location name within your FCSky platform (found under Settings → Franchise Location → Manage Franchise Locations).

  • Division
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter Division
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select the user.officelocation value

Important: This value is only required for Divisional & Hierarchy users (e.g., within the 'National Manager' Role).

Tip: You can use any available attribute for the Franchise User Type value, as long as it is an exact match of an Area/Region name within your FCSky platform (found under Settings → Division Management → Manage Division).

  • World Manager Country
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter WorldManagerCountry
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source’ field, select the "Transformation" option, then complete as below:
      • Transformation: Select the "RegexReplace()" option
      • Parameter 1: Select the "Attribute" option
      • Attribute name: Select the user.country option
      • Regex pattern: Enter AU
      • Replacement pattern: Enter Australia

Important: By default, the user.country value from Azure AD gets abbreviated to the country code - e.g., Australia will become AU. This will cause a validation error, as the FCSky platform expects the full country name. Hence the reason we used "Transformation" as the 'Source' for this particular claim.

Note: The above instructions are to replace the country code for Australia specifically. So, you will need to amend the (transformation) field values, based on your applicable country/countries.

  • World Manager Account Group
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter WorldManagerAccountGroup
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select one of the extension attribute values

Tip: You can use any available Account Group name from your WM platform.

  • World Manager Account Group Type
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter WorldManagerAccountGroupType
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select one of the extension attribute values

Important: This value is only required for Divisional & Hierarchy users.

Tip: The only accepted values for the World Manager Account Group Type attribute are "world-view" or "country-view". This refers to whether the Account Group is created at world-level or within a country (on your WM platform).

  • World Manager Employee Only
    • Click on the “Add new claim” button
    • In the ‘Name’ field, enter WorldManagerEmployeeOnly
    • Click on the ‘Choose name format’ section (to expand), then action the following (below):
      • In the ‘Name format’ drop-down, select the “Unspecified” option
    • In the ‘Source attribute’ drop-down, select one of the extension attribute values

Important: This value is only required for users that you want to restrict to World Manager access exclusively.

Tip: The only accepted values for the World Manager Employee Only attribute are "Yes" or "No".

Once finished, you should be left with something like this:

Important: To ensure correct functionality, all attribute names must be an exact match for what appears in the 'SAML Attributes' tab of the connector you configured within your FCSky platform.

Note: The value under the 'Required claim' section cannot be removed. However, it is not required and will be ignored.

Assign Users/Groups to App

1. Go to Manage → Users and groups

2. Click on the “Add user/group” button

3. Under the ‘’ section, click on the “None selected” link

4. In the text field, enter the name of a user or group you wish to add to the role, then click on the result that appears (to add)

5. Repeat step 4 to assign the app for all applicable users/groups

6. Click on the “Select” button (when finished)

7. Click on the “Assign” button (to save)

If you require any assistance with configuring SAML SSO for your FCSky platform, please contact our Support Team at helpdesk@franconnect.com.

Was this article helpful?
0 out of 0 found this helpful

Table of Contents