We noticed that JavaScript is disabled in your browser. We suggest enabling it for a better experience.
We noticed you're using an older version of Internet Explorer. We suggest you update to the latest version for a better experience.
Skip to main content
Print

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
    Create a new connection to OpenForms
  4. When prompted, copy the Tenant URL and Secret token
    secrettoken.png
    These items are essential to the connection process and will not be displayed again, so make sure you paste them somewhere safe.

Install the OpenForms enterprise app 

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
    enterprise-apps.png
  3. Select New application
    newapplication.png
  4. Select Search Application and search for OpenForms
    Search-OpenForms.png
  5. Select the OpenForms application and Sign up for OpenForms 
    Select-OpenForms.png
  6. You will be redirected to the Microsoft login page. The user who logs in here must have a Cloud Application Administration role in their Microsoft account.
  7. After logging in, you will be asked to consent to the permissions needed for OpenForms to connect with Azure AD. Accept these permissions to continue.

Upon completing this process you’ll be taken to the OpenForms login page. To validate that the installation has been completed log into Azure AD and navigate to Enterprise applications. A new application should now be displayed there for OpenForms.

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

Establish a connection to OpenForms

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

  1. Go to Enterprise applications > OpenForms
  2. Select Provisioning
    OF-Provisioning.png
  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
    testconn.png
  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 > OpenForms > Provisioning
  2. Scroll to Mappings
    mapping.png
  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. Delete all other user attributes
  9. Save your user mappings
  10. Scroll to Settings
  11. Use the Scope dropdown to define what data you'd like to send to OpenForms
    scope-dropdown.png
    By selecting Sync only assigned users and groups you can ensure you reduce the scope of sent data. We strongly discourage selecting Sync all users and groups and provisioning your entire Azure AD staff directory to OpenForms. Syncing all data 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
  12. Set Provisioning Status to On
  13. 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. 

cycle-complete.png

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 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 > OpenForms > Provisioning > Settings
  2. Select Sync only assigned users and groups from the Scope dropdown
  3. Save your settings 
  4. Go to Enterprise applications > OpenForms > Users and groups
  5. Select Add user/group
    add-group.png
  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 > OpenForms > 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 > OpenForms > 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
    source-object-scope.png 
  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 > OpenForms > 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 > OpenForms > Provisioning and finalize your provisioning setup

Pause provisioning

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 > OpenForms > Provisioning
  2. Select Stop provisioning
    stop-provisioning.png

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. 

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
    delete.png
  4. Repeat the process above for Enterprise applications > OpenForms
Was this helpful?

Related topics