Set up Azure AD to work with OpenForms

This article describes the process of setting up Microsoft Azure AD for use with the OpenForms Azure AD connector.

This information is intended for Azure AD administrators, and assumes a working knowledge of Microsoft Azure AD. 

If you're an OpenForms account owner working with an Azure AD admin to set up the connector, see how the Azure AD connector works for everything you need to know. 

Before you begin

To complete this process you’ll need the assistance of an OpenForms account owner, or your own OpenForms user profile with account owner role.

If you’re not an OpenForms account owner yourself, you should discuss an implementation plan for the Azure AD connector with your organization’s OpenForms team before commencing the connection process. 

Retrieve your secret token and tenant URL

To establish an initial connection to OpenForms

1. Log into OpenForms as an account owner, or ask an account owner to log in for you
2. Go to Integrations > Azure AD 
3. Select Connect
   
   
4. When prompted, copy the Tenant URL and Secret token
   
   
   These items are essential to the connection process and will not be displayed again, so make sure you paste them somewhere safe.

Create an OpenForms enterprise app

To provision Azure AD group and user data to OpenForms, you currently need to create a custom OpenForms enterprise application within Azure AD. This simple process is a temporary workaround while Microsoft finalizes an official OpenForms app for the Azure AD app gallery. 

Once you've retrieved a tenant URL and secret token from OpenForms

1. Log into Azure AD as an administrator
2. Go to Enterprise applications
   
   
3. Select New application
   
   
4. Select Create your own application
   
   
5. Give your application a name (such as “OpenForms Provisioning’) and select integrate any other application
   
   
   To avoid confusion with the official OpenForms gallery app currently in development at Microsoft, it's best not to name your app "OpenForms"
6. Select Create

This will create an Azure AD enterprise application which you can use to provision data to OpenForms. Upon creating your application you’ll be taken to your application’s detail page to complete the next step in this process

If you need to return to this page in future, log into Azure AD and go to Enterprise applications > Your custom OpenForms app

Establish a connection to OpenForms

Once you’ve created a custom OpenForms application in Azure AD

1. Go to Enterprise applications > Your custom OpenForms app
   
2. Select Provisioning
   
   
3. Select Get started
   
4. Select Automatic from the Provisioning mode dropdown
5. Enter your OpenForms tenant URL and secret token
6. Select Test your connection
   
   
7. If your connection is successful, Save your configuration. This will reveal additional provisioning settings
   If your connection is unsuccessful, double check that you've pasted your tenant URL and secret token correctly. If you've copied these incompletely, you'll need to restart the connection process in OpenForms to regenerate them. 

Provision data to OpenForms

Once you've successfully connected your custom application to OpenForms, you’ll need to configure its provisioning settings

1. Go to Enterprise Applications > your custom OpenForms application > Provisioning
2. Scroll to Mappings
   
   
3. Select Provision Azure Active Directory Groups
4. Map the following group attributes:
   

   Azure AD attribute	OpenForms attribute
   displayName	displayName
   objectId	externalId
   members	members

5. Save your group mappings
6. Select Provision Azure Active Directory Users
7. Map the following user attributes
   

   Azure AD attribute	OpenForms attribute
   userPrincipalName	userName
   switch([IsSoftDeleted], ,"False", "True", "True", "False")	active
   mail	emails(type eq "work"), value
   givenName	name.givenName
   surname	name.familyName
   objectId	externalId

8. Save your user mappings
9. Scroll to Settings
   
10. Use the Scope dropdown to define what data you'd like to send to OpenForms
    
    
    We strongly discourage provisioning your entire Azure AD staff directory to OpenForms without reducing the scope of sent data. This can affect your user quota and clutter the Azure AD connector interface.For information on how to define the scope of provisioned data, see What data to provision
11. Set Provisioning Status to On
    
12. Save your settings

Once you have set provisioning to "On", Azure AD will queue a data sync with OpenForms. Depending on Microsoft server resources, this will usually occur within an hour.

As this is happening, you can let your OpenForms account owner know that they can complete the connection wizard in OpenForms. 

However, they should not begin assigning OpenForms roles to Azure AD User groups until the first sync Azure AD sync is complete. 

You can check the progress of this sync at Enterprise applications > Your custom OpenForms application > Provisioning

What data to provision

There are two methods of defining the scope of data sent to OpenForms

• Whitelist specific Azure AD user groups 
• Filter the groups and users provisioned by their attributes

Whitelist specific groups

This method requires a Premium Azure AD license. 

For most organizations, whitelisting specific Azure AD user groups is the simplest way to ensure that only staff that need OpenForms are granted roles through the connector. 

To use this method, you'll need an active directory structure containing groups that correspond to particular OpenForms roles.
To make life easier for the OpenForms account owners that will assign these staff roles in the AD connector, it's best to create new groups for these staff with descriptive names reflective of the roles they'll require (for example: "openforms_humanresources_reviewer") 

Once you've set up those groups,

1. Go to Enterprise applications > your custom OpenForms application > Provisioning > Settings
2. Select Sync only assigned users and groups from the Scope dropdown
3. Save your settings 
4. Go to Enterprise applications > Your custom OpenForms application > Users and groups
   
5. Select Add user/group
   
   
6. In the Add assignment screen, choose the groups you would like to assign. 
   As the OpenForms Azure AD connector cannot assign roles to individual users, make sure you assign specific groups, rather than users
7. Return to Enterprise applications > your custom OpenForms application > Provisioning and finalize your provisioning setup

Filter provisioned groups by their attributes

Instead of whitelisting particular groups, you can filter the groups and users sent to OpenForms by their attributes, such as the presence of "HR" in a group or user attribute
Because this method does not rely on a group naming structure, it can be more difficult for OpenForms account owners to understand when assigning roles to Azure AD user groups

 Once you've decided on the attributes you'd like to filter by,

1. Go to Enterprise applications > your custom OpenForms application > Provisioning > Settings
2. Select Sync all users and groups from the Scope dropdown
3. Save your settings 
4. Go to Mappings
   
5. Select Provision Azure Active Directory Groups
6. Under Source object scope, select all records
   
    
7. Select Add scoping filter
8. Set up your filter using the available options (as described in this article)
9. Select OK
10. Add as many additional filters as you need
11. Select OK
12. Save your settings 
13. Return to Enterprise applications > your custom OpenForms application > Provisioning > Mappings
14. (Optional:) Select Provision Azure Active Directory Users and apply additional filters for user attributes (for example, an "OpenForms" attribute)
    
15. Save your settings
16. Return to Enterprise applications > your custom OpenForms application > Provisioning and finalize your provisioning setup

If at any time you want to pause provisioning data to OpenForms (for example, if you are restructuring your Azure AD staff directory)

1. Go to Enterprise applications > Your custom OpenForms application > Provisioning
2. Select Stop provisioning
   
   

This will temporarily prevent changes in Azure AD from propagating to OpenForms.

Any users that were assigned roles in OpenForms based on their Azure AD user groups will keep those roles and access to OpenForms until provisioning is resumed, even if they are moved or deleted in Azure AD. New staff staff added to groups in Azure AD will not be assigned roles in OpenForms, however. 

Streamline user logins

When users managed through the Azure AD connector first log into OpenForms, they will be asked to consent to the use of their Azure AD data.

To proceed to OpenForms, users must accept this useage.

You can bypass this request and streamline your OpenForms users’ login experience by granting consent on their behalf in Azure AD. To do this,

1. Log into OpenForms as a user managed by Azure AD and grant OpenForms consent to use your Azure AD data
   
   
   This first login will create an "OpenForms" gallery app in your Azure AD admin interface. 
2. Log into Azure AD as an admin and go to Enterprise applications > OpenForms
   
3. Select Permissions
4. Select Grant admin consent for your Azure AD tenant
   
   

Disconnect from OpenForms

To permanently disconnect from OpenForms, 

1. Disconnect from Azure AD in OpenForms
2. Go to Enterprise applications > your custom OpenForms application > Properties
3. Select Delete
   
   
4. Repeat the process above for Enterprise applications > OpenForms