Articles in this section

See more

Microsoft Entra ID (formerly Azure Active Directory) based User Provisioning

Avatar
Jack Davenport
  • Updated
Follow

The Folio supports provisioning of new users using Microsoft Entra ID (formerly Azure Active Directory). This feature is available with Enterprise 1000 and above user licenses. 

Entra ID based user provisioning will enable you to: 

  • Create new Full Users or Lite Users in Folio from Entra ID.
  • Apply a User Profile (for access rights) to Full Users from Entra ID
  • When a user is set inactive in Entra ID or removed from the enterprise app in Entra ID, they will be suspended in Folio. You will need to retire these suspended users and transfer their responsibilities directly in the Folio not via Entra ID.
  • Once provisioned, Users will be able to Single Sign On (SSO) to Folio. SSO is where the user logins to Folio with their Entra ID credentials rather than having to use a Folio only password. 

Before you Start

Please ensure that you note the following steps before you start:

  • The default mapping has the users Business Unit being mapped to Department, in this approach you will need to have an Business Unit in Folio that is an exact match to the department name.
    • If your departments are not matching to Folio there is an option to setup an mapping, so it will change from "Entra Department" to "Folio Business Unit" when importing the user, this is explained during the mapping process
  • If you are wanting to import Locations onto your users then the Locations in Folio must match the Entra ID attribute called Office Locations. Folio will not provision users with Locations that do not exist in Folio. If you are not wanting to import locations then you can choose to not map it later on
  • Before starting if you have previously created a Folio enterprise application via ‘App Registrations’ (for Single Sign on) this will need to be removed.
  • Make sure you are in the correct directory in Azure

Sandbox & Production

  • We recommend that you only have Entra ID based user provisioning on your production Folio instance.
  • You can test Entra ID based provisioning in Sandbox and when you are ready to activate user provisioning in production you must follow these steps:
    • Delete the Sandbox enterprise app.
    • Create a new Production enterprise app.
    • You must NOT change the Tenant URL in the Entra ID provisioning setup on the sandbox enterprise app to the Folio production URL or vice versa as this will not work.
  • While we recommend that you only have user provisioning on your production instance, you can  have Single Sign On (SSO) on both Sandbox and Production. (The steps in this article will walk you through setting up SSO on both Sandbox and Production.)
  • Note: Folio will not stop you from setting up user provisioning on both Sandbox and Production. However it is vital to note that if the production database is copied to sandbox or vice versa (typically in the implementation phase), you must delete the 'old' enterprise app and set up the enterprise app again in the instance that has been copied over. This must be done to avoid the risk of User ID mismatches. 

Setting up Azure Single Sign on to Folio

To enable Provisioning with Entra ID you will first need to set up Folio in Enterprise Application.

  1. In Azure Portal click on Microsoft Entra ID

OPIz5Lnsb3.png

  1. Click on Enterprise Applications under Manage

imjQxPe0Pu.png

  1. Click on New Application

DrAckdiow2.png

  1. Click on ‘Create your own application’

N7NP9B8Lw5.png

  1. Use the Following to setup the new app
image30.png

What's the name of your app

Folio

What are you looking to do with your application

Integrate any other application you don’t find in the gallery (Non-gallery)

Click Create at the bottom to create the app

  1. On the sidebar click on Single sign-on under Manage

rF3NZSncST.png

  1. Click on SAML

Ut7w7cEVTK.png

  1. In the Basic SAML Configuration box click on edit

 

XE1Cmp2gBT.png

  1. Click on Add identifier under Identifier (Entity ID)

NM5SMxnepE.png

  1. Enter your Folio production URL into the field and tick Default

  1. Click on Add reply URL under Reply URL

  1. Then Enter your production URL as shown below

 https://{{$fol_name}}.foliogrc.com/d/users/auth/saml/callback - This one should be marked as default

Note : If you are wanting to use Single Sign on in your sandbox but will not be setting up user provisioning to sandbox you can click Add reply URL again and add in the url below for sandbox

https://{{$fol_name}}.sandbox.usefolio.com/d/users/auth/saml/callback

  1. Click Save on top of the Basic SAML Configuration screen.

  1. Then click close with the x on the right of the screen

You should now open a notepad or word doc as you will need to keep some URL's that Azure will give you handy for later use in Folio

Issuer/ Identifier(Entity ID) https://{{$folio_name}}.foliogrc.com
Reply URL (Assertion Consumer Service URL) https://{{$folio_name}}.foliogrc.com/d/users/auth/saml/callback
https://{{$folio_name}}.sandbox.usefolio.com/d/users/auth/saml/callback
App Federation Metadata URL STEP 15
Login URL STEP 16
  1. In ‘SAML Certificates’ section copy ‘App Federation Metadata Url’ into the Reference table above

  1. In ‘Set up Folio’ section, copy ‘Login URL’ into the Reference table above

  1. Now you will setup the user profiles you are using for EntraID as App Roles

Creating App Roles

To Provision users into User Profiles you will be setting up App Roles for each profile you have, then when you want to provision someone to Folio you add them an App Role and Folio will create them as a user and then give them the user profile that is associated with the App Role. 

Additionally you can also use App Roles to provision lite users. For this you will just need to create an App Role called Lite User which will cause Folio to provision the user as a lite user. 

From the SAML page click on

  1.  
    1. Click Home on the top bread crumbs
  2. 2. Click Microsoft Entra ID on the left sidebar
  3. OPIz5Lnsb3.png
  4. 3. Click App Registrations on the left sidebar
  6. 4. Then Click The All Applications tab
  8. 5. And then Click on the Folio application you created earlier

  1. Click on App Roles on the sidebar under Manage, and then click Create App Role

You will now set up all of the user profiles you are going to use with Entra from Folio as App Roles, Clicking Create App Role - filling in the fields as below, clicking apply and then repeating until you have created roles for all the profiles you require. 

Azure Field

What to put into it

Display Name

Copy the name of the user profile exactly

Allowed Member Types

User/Groups

Value

Copy the name of the user profile but replacing spaces with ‘_’

Description

The description of what the user profile allows an user to do

Do you want to enable this app role?

Tick

image9.png

Now that you have created all the AppRoles you will now need to assign users to these roles to have them provisioned in Folio

  1. Return to the Folio Application and go to the Users and Groups screen
    1. Click Home on the top bread crumbs
  3. 2. Click Microsoft Entra ID on the left sidebar
  4. OPIz5Lnsb3.png
  5. 3. Click Enterprise Registrations on the left sidebar
  6. imjQxPe0Pu.png
  7. 5. And then Click on the Folio application you created earlier
  9. 6. Click on Users and groups
  1.  

21. Click Add user/group

  1. Click on None Selected under users

  1. then select all the users you would like to add to the role (user profile) you created and finally click Select

image1.png

  1. Click on None Selected under Select a Role

  1. Select the App Role (User Profile) you created earlier that you would like all of the users you have selected to have in Folio and click Select once you've selected it. 

image6.png

  1. Click Assign

image24.png

Repeat this with all the users and roles you want to be provisioned in Folio

  1. Now open Folio and go to the admin screen

  1. Sign On and Security on the admin screen

  1. Then click Edit

  1. Check ‘Single Sign On through SAML’ and referring to the reference table on step 16 enter the corresponding values into the corresponding fields, then click update

Now when you log into Folio you will see that you can login using Azure Single Sign on

Setting up Azure Provisioning

Note: For the Provisioning you will need to ensure that the Business Units (departments in entra), Locations and User Profiles you are going to assign to users are setup in Folio

  1. On sign on and security page click edit and tick the Scim enabled checkbox for your azure setup and click update

Note: If the Scim Enabled checkbox is not there please email our support team who can enable it for you

  1. The view screen will now have Scim URL and Scim Token which will both be used in a step 5

  1. On azure’s homepage go to
    1. 1. Click Microsoft Entra ID on the left sidebar
    2. OPIz5Lnsb3.png
    3. 2. Click Enterprise Registrations on the left sidebar
    4. imjQxPe0Pu.png
    5. 3. And then Click on the Folio application you created earl
    6. 4. Click on Provisioning
    8. 5. Click on the Get Started button

4. Set the following

Entra Field What Value to put into it
Provisioning Mode Automatic
Tenant URL The SCIM Url folio gave you
Secret Token The Scim Token folio gave you

image4.png

5. Click on Mappings to expand the mappings section,

  1. then click on Provision Microsoft Entra ID Groups
  2. Set the Azure field 'Enabled' to No
  3. then click on Provision Microsoft Entra ID Users

9. Set the following

Azure Field Value
Enabled Yes
Source Object Scope All Records
Target Object Actions Create, Update, Delete

image23.png

 

10. Scroll down to the Attribute Mappings table and click on show advanced options,

 

11. Click Edit attribute list for customappsso

 

12. You will need to add the three attributes to the Attribute list

Note: If you are choosing to not import Locations then you can skip out on adding officeLocation

Name Type Referenced Object Attribute
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:officeLocation String  
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:appRole String  
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:escalationUser Reference urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

image8.png

Then click save to return to the Attribute mapping screen

 

13. You will need to add the three mappings below to have the integration work,

Mapping Type

Microsoft Entra ID Attribute (Source Attribute)

Customappsso Attribute (Target Attribute)

Matching precedence

Mapped to Folio User (info only, these don't need to be put into the mapping)
  displayName displayName   Name
Expression Expression:SingleAppRoleAssignment([appRoleAssignments])

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:appRole

   User Profile (one only)
  department

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department

  

Business Unit

You can also add the following rows if you would like to have these additional fields come through to Folio

Mapping Type Microsoft Entra ID Attribute (Source Attribute) Customappsso Attribute (Target Attribute) Matching precedence Mapped to Folio User (info only, these don't need to be put into the mapping)
  jobTitle title   Job Title
Expression mobile phoneNumbers[type eq "mobile"].value   Mobile
  objectId externalId   external_id (unique)
Direct manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:escalationUser   Escalation User
Direct physicalDeliveryOfficeName urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:officeLocation   Location

Note: If you are not importing Locations then skip the last Location row

Once you have setup everything you want to come through to Folio click save on the top

 

14. Click Start Provisioning and the users you have setup will start to be brought into folio

Setting Up Department to Business Unit mapping

Folio requires a valid Business Unit when creating or updating a user, so if the department you pass for a user does not have a corresponding Business Unit then it will fail. 

The solution to this problem is to change the mapping from being a direct map to an expression, in doing this you are able to set up the expression so that it will convert from your departments to a valid Folio business unit. 

There are a few additional things you will need to consider before going with this approach:

  • You will need to keep the mapping updated, meaning if any departments or business unit names are change then the mapping will need to be updated
  • You will need to list all Departments that users have in this expression and their corresponding business units, even if an matching business unit exists for that department - if there is not a corresponding key it will go to the default
  • If a mapping is not found for the department it will go to the default option, this can be mapped to an business unit or can be left blank if you want that to fail (this might be important as you don't want to create a user with the wrong business unit because of access rights)

To setup the expression

  1. Go to Enterprise Apps
  2. Select the Folio application you created previously
  3. Click on Provisioning on the left bar
  4. Click on Attribute Mapping (Preview)
  5. Click on Provision Microsoft Entra ID Users
  6. Click on Edit for the attribute map row for department

Change the Mapping Type from Direct to Expression

You will now need to create an expression that will change the department name into the Folio business unit name, we recommend using the switch expression (see the microsoft help article here for more information) 

An example of an Switch Expression you could use is below, where:

  • The default business unit is called "Example Corp" (this is what all users whose department is not listed in the switch will default to)
  • I have a department called "Financial Services" which will map to the Folio Business unit called "Finance"
  • I have a department called "Operational Services" which will map to the Folio Business unit called "Operations"
Switch([department], "Example Corp", 
"Financial Services", "Finance", 
"Operational Services", "Operations")

Note: for readability you can make it a multi line expression, but upon saving it will change it to one line. 

Now click save, and when provisioning next happens it will use this expression to change from Department to Folio Business Unit

Related articles