This article describes how the Azure AD connector works in plain language, and outlines the key choices an OpenForms account owner will need to discuss with an Azure AD administrator to configure the connector.
The concepts covered are:
How the connector works
The Azure AD connector works by receiving information about user groups from Azure AD, and assigning those groups OpenForms roles.
Once an Azure AD user group is assigned a role through the connector, staff members within that group become OpenForms users. They can login to OpenForms using their Microsoft credentials administered in Azure AD, and perform any tasks associated with their OpenForms roles.
Staff members can be assigned to multiple Azure AD user groups.
Users added to OpenForms through the Azure AD connector cannot be managed individually through the OpenForms Admin > Users interface.
If a staff member is removed from an Azure AD user group, they lose any OpenForms roles that have been assigned to that group. If this leaves them without an OpenForms role, their OpenForms account is deactivated.
If a staff member’s profile is deactivated or deleted in Azure AD - when they leave your organization for example - their OpenForms account is automatically deactivated.
Managing staff in Azure AD (user groups)
To give an individual staff member access to OpenForms, your Azure AD administrator or IT team will need to add that staff member to one or more Azure AD groups that have been assigned a role in OpenForms.
What you need to decide
You should discuss with your Azure AD administrator:
- Who will add staff members Azure AD user groups with access to OpenForms?
- Will this be your Azure AD administrator, another member of your IT team, or an OpenForms account owner that has access to Azure AD?
- If this person is not an OpenForms account owner, how the account owner communicate staff changes to an appropriate member of the IT team?
What data is sent to OpenForms (scope and attributes)
Your organization’s Azure Active Directory can contain a lot of information, not all of which is necessary to use the Azure AD connector.
To prevent the Azure AD connector from listing irrelevant user groups your Azure AD administrator will narrow down the information that is sent to OpenForms by defining the scope and attributes of that data.
Scope
Most organizations don’t need OpenForms accounts for all of their staff.
Your Azure AD administrator can filter which user groups are provisioned to OpenForms by changing the scope of the information sent.
There are two ways to do this:
-
Allowing Azure AD to send only whitelisted user groups to OpenForms
-
Allowing Azure AD to send all user groups to OpenForms, but filtering the groups that are sent by particular group or user attributes
Which option best suits your organization depends on how your AD administrator or IT staff collect staff members into user groups.
What you need to decide
Talk to your Azure AD admin about how your user groups are organized in Azure AD.
-
If your organization creates user groups specifically for OpenForms, then scoping only whitelisted groups may suit it best.
In this scenario, you may have user groups in your active directory with names like “OpenForms_Parks&Rec_admin” or “OpenForms_Finance_Reviewer”.
-
If your organization collects staff according to other criteria such as their department or job, you may want to add an “OpenForms” attribute to the users that need access to OpenForms.
In this scenario, you may have user groups with names like “finance” or “parks and rec”, containing users with the “OpenForms” attribute.
Because OpenForms roles are assigned to entire user groups, not individual users, you may find it useful to create specific OpenForms user groups in Azure AD regardless of how your organization currently groups staff in Azure AD. For example, you may want to add some members of your finance department to an Azure AD user group for OpenForms admins, and some members to an Azure AD user group for OpenForms reviewers. Your Azure AD admin can scope all your organization's user groups to OpenForms, without applying filters or whitelists. Because this can clutter the Azure AD connector with user groups that don’t need OpenForms access, and make it easy to exceed your OpenForms user limit, we do not recommend this approach.
Attributes
Attributes are the pieces of information which make up an Azure AD user profile.
Some attributes in a user’s profile might be their first and last name, their staff ID, their manager, or their direct reports.
Right now, OpenForms can use these user attributes:
- Username
- Status
- Email address
- First name
- Last name
- ExternalID
User groups also have attributes, such as their name or number of members.
OpenForms can use the following group attributes:
- Display name
- External ID
- Number of members
What you need to decide
The attributes listed above will be configured by your Azure AD administrator when they add OpenForms to your Azure AD environment.
In future updates, OpenForms may add support for additional attributes. When that happens, you may want to discuss with your AD administrator whether these are useful to your organization. They will need to configure Azure AD to send these additional attributes to OpenForms.
Turn on the data tap (provisioning)
The process of sending Azure AD user groups to OpenForms is called provisioning.
Technically, all of the concepts outlined above form part of the provisioning process, but for the purposes of communicating with your AD administrator, we’ll limit “provisioning” to enabling or disabling the flow of information from Azure AD to OpenForms.
Once you and your Azure administrator have made the setup decisions outlined above and your Azure administrator has completed the rest of the steps outlined in the our setup guide for Azure AD administrators, it is time to start provisioning and turn on the data tap between Azure AD and OpenForms.
Initial provisioning
When you first start provisioning data to OpenForms, it can take a couple of minutes for Azure AD to send the data you've scoped to the Azure AD connector.
While this is happening, you'll see the list of user groups in the Azure AD connector begin to populate.
Your Azure AD Azure administrator will let you know when this process is complete and you can begin assigning those groups OpenForms roles.
It's important to wait until this initial process is complete, otherwise you may miss some user groups when assigning roles. User provisioning happens within an hour.
Ongoing provisioning
While provisioning is active in Azure AD information will continue to flow from Azure AD to OpenForms (this occurs every 40 minutes).
Staff that are added, removed or moved between user groups in Azure AD will automatically assume the correct roles in OpenForms.
What happens when provisioning is paused
If provisioning is paused (either by your Azure AD admin or due to an outage) OpenForms will not receive new information from Azure AD, so changes to the staff within provisioned Azure user groups, or changes to the user groups scoped to OpenForms, won’t be reflected in OpenForms until the connection is restored.
OpenForms will continue to use data that it has already received from Azure AD, so staff members that have already been assigned roles can continue to login to OpenForms and perform the tasks associated with their roles.
Very occasionally, Microsoft's login processes may be disrupted by an outage, in what case OpenForms users managed through the Azure AD connector will not be able to login until the problem is resolved by Microsoft. We recommend maintaining a backup account owner profile managed through the OpenForms admin interface in case this happens. Use this account to access any time-critical forms or responses.
What you need to decide
Because of the nature of the connection to Azure AD, OpenForms can’t indicate whether provisioning to the Azure AD connector is active. So it’s important that you and your Azure administrator communicate about the status of provisioning.
You may also, at times, want to ask your Azure administrator to pause provisioning.
This is especially useful if you or your IT team are re-organizing your Azure user groups and you don’t want this to be reflected in OpenForms until the process is complete.
Streamlining your users’ first login (admin consent)
Once you’ve assigned staff members an OpenForms role using the Azure AD connector, they can log in to OpenForms using their Microsoft SSO credentials within your organization.
The first time they do this, they’ll be prompted to give OpenForms permission to access their Azure AD profile.
Your Azure AD admin can streamline your staff members’ login experience by granting permission on their behalf, so they don’t see this screen.
What you need to decide
If you’d like to streamline your staff members’ login experience, so they aren’t presented with a permission screen before they start work for the first time, ask your Azure AD administrator to grant OpenForms admin consent to staff data.
The only effect this setting has on your staff members’ experience is to bypass the permission screen above.
You may choose to allow staff to see this screen in the interests of transparency, or bypass the screen to keep them on-task.
What's next?