Azure Active Directory SCIM API

Introduction

You can integrate with Microsoft Azure Active Directory (Azure AD) via federated authentication or using SCIM (System for Cross-domain Identity Management), allowing users to log in to Flexopus using their existing Azure AD credentials.

Flexopus can be linked to an instance of Microsoft Azure Active Directory (Azure AD) via federated authentication. This is a process whereby the username and password of an account from a first directory system are provided in such a way that the same username and password can also be used in other systems.

What are the advantages of SCIM?

With the SCIM interface, you can better automate user administration between your Identity Provider (IdP) and us as Service Provider (SP). The following advantages result from this:

• Synchronize and deploy user groups
  You can manage user groups externally in your IdP. Through SCIM, external groups including members can be sent to Flexopus.  These groups are created in Flexopus as “read-only” groups and can only be managed externally by your IdP. The groups can then be used normally for the administration of the workstations. All changes in these groups are sent to Flexopus within 40 minutes. 
• Synchronize and provide user profiles
  User profiles and the changed and associated attributes (name, job title, department, etc.) can be synchronized automatically. Every change in your IdP is usually sent to Flexopus within 40 minutes, so user profiles can be kept constantly up-to-date. In contrast to SAML2, the data exchange runs during the session time and not only during the login attempt.
• User profiles before the first login
  By combining the two benefits, you can basically create a group in your IdP. You can assign group to Flexopus. Through this assignment, the members of the group can also be sent to Flexopus before the first login.
  Example: The newly hired employees can be sent to Flexopus before the first working day, so that the responsible colleagues can possibly manage local user groups in Flexopus.
• Automatically archive and delete user profiles
  The provided user profiles including group assignments can also be automatically deactivated / archived. Should a staff member lose access to the application. The IdP reports through SCIM to Flexopus that the employee no longer has access to the application. This can happen for several reasons: the Employee was dismissed, or the IT Administrator has intentionally or unintentionally revoked the authorization. Thus, the employee is archived in Flexopus. With an additional data protection setting, the archived users can then be automatically deleted from Flexopus after X days.

Setup Instruction Manual

Azure Active Directory SAML2 SSO

Introduction Connect Flexopus with your Entra Active Directory (formerly known as Azure Active Directory) via a SAML2 Single Sign On integration. With the integration, you can manage through your Active Directory which users should have access to Flexopus and force them to use their Microsoft AD credentials for the login.

Flexopus Help CenterDaniel Fafula

STEP 1 - Configure the SCIM API

Go to your Azure Active Directory as an administrator. Visit the Enterprise Application page and select the Flexopus application that used for the SAML2 SSO connection. We named it Flexopus SSO / SCIM in our example.

Visit the menu point Provisioning and click on the Get Started button.

Select, instead of manual provisioning mode, the Automatic option.

Go to your Flexopus Dashboard as an administrator and visit the page Dashboard Settings > Integrations. Here you can see the Tenant URL and you can generate the SCIM API token.

Take the Tenant URL and the Secret Token and paste them under the Admin Credentials section in the Active Directory. After that, click on the Test Connection button. You should receive a success message in the right top corner.

STEP 2 - Configure attribute mapping

Set up the attribute mappings. Open the Mappings dropdown and select the Provision Microsoft Entra ID Users option:

The default setting of the SCIM API sending more data than we need. Delete the unnecessary fields as listed below. After editing the attributes, save your changes.

As next, you need to validate the user profiles that will be sent through this automated interface to Fleoxpus. Flexopus expects to receive user profiles with an email address, however in some cases there are user profiles in Active Directory, which do not have any email addresses, this synchronization of these profile swill fail. To avoid this to happen, the invalid user profiles need to be filtered.

Select the option Source Object Scope > All record to create a scoping filter, the click on the Add new filter group option.

On this window, enter the following filter:

• Source attribute: mail
• Operator: IS NOT NULL

Name the filter as: Email validation. Save the settings. (You have to save multiple times.)

The final settings will look like this for the User settings look like this:

Go to the general provisioning settings and select the option Send an email notification when a failure occurs and enter scim@flexopus.com email address. Though this email address, we can be informed, if Microsoft is blocking your integration.

The SCIM API is an automated API causing many requests between Flexopus and Microsoft. In case your configuration changes (Flexopus is moved to another domain, etc.) the requests can not be processed. In this case, Microsoft is blocking, stopping the integration. The only way to be notified about this block is this email address. Of course, you can also enter your own internal IT email address to be received about these notifications. Save the changes.

STEP 3 - Add groups and users for the provisioning

Before starting the provisioning, you need to configure which groups and user should be provisioned.

To assign groups and users, navigate to the Users and groups menu tab and click on the Add user/group button in the top. Remember the golden rule: Only the explicitly assigned groups and users will be provisioned. You may have more groups in your active directory, still only the selection will be used for this enterprise application.

User groups

Introduction Here you can see a list of action you can do with user groups to use and manage them as an administrator: How to manage the user groups? * Manage groups manually * Manage groups via the SCIM API * Manage groups via SAML2 (memberOf) * Import users and groups (CSV and XLSX)

Flexopus Help CenterDaniel Fafula

STEP 4 - Start provisioning / Testing

Now, you configured all the necessary options for the SCIM API. Navigate to the main provisioning screen and click on the Start provisioning button.

As you can see on the right side, the provisioning will be executed latest in 40 minutes, which means that you shouldn't expect an immediate change in Flexopus.

Once the provisioning started, you can check the logs in the View provisioning logs tab.

Once you assigned a group and started the provisioning, you can expect the following changes in Flexopus. The groups will be provisioned with an external marking to Flexopus, which means that you can not edit the groups locally in Flexopus. You can not change the names, add user or delete user from the group. The single source of truth will be the group structure in your Active Directory.

You can use the groups for access management within Flexopus similar to the other internal or system groups. 

Learn more about groups here:

User groups

Introduction Here you can see a list of action you can do with user groups to use and manage them as an administrator: How to manage the user groups? * Manage groups manually * Manage groups via the SCIM API * Manage groups via SAML2 (memberOf) * Import users and groups (CSV and XLSX)

Flexopus Help CenterDaniel Fafula

Best practices using SCIM

The fact that you can synchronize groups from your Active Directory to Flexopus doesn't mean that you should manage all your groups through SCIM. We recommend syncing only a limited amount of groups, that also has a reason to be synchronized. The Active Directory is usually the playground of the IT department to manage access to applications and services, and not necessary to manage desk assignment on the user level.

Manage and maintain groups in the Active Directory, which potentially can be used for other use cases as well. A group like AllCompanyUsers can be managed in Active Directory, but a group like DepartmenAWorkstationGroup2 could be managed in Flexopus directly.

Decide who should maintain the group for the desk assignment. Is it the responsibility of the IT department or is it the responsibility of the facility management, the departments, or the HR? The once that suppose to manage the groups shall have access to the group management. In most of the cases, the IT has access to the Active Directory and the other has no access. We should avoid creating support tickets for each change per group.

Suggestion - One external group

A very simple solution is to synchronize only one group. Let's name this groups AllFlexopusUsers. This group contains the users that suppose to have access to Flexopus.

Once you connected the AllFlexopusUsers groups and start the provisioning, the group itself and all the users within the groups will be synchronized to Flexopus, even if they did not log in into Flexopus yet.

This way we can provision all the users to Flexopus, and the Flexopus administrators can group them locally at Flexopus as they wish. You can grant permission to Flexopus administrators to create and manage other groups in Flexopus. This way, you as IT admin can outsource the management of the groups to the once that are interested in the management of the groups. You have only one group to manage in the AD.

USE CASE - New employee starting (create through provisioning)

In case a new employee will start on the first day of the next month, we will need to allow the new employee to book the right resource from day one. Which means that the employee should have the right groups for reservation before the first login. If we add the user as a part of the onboarding process to the AllFlexopusUsers group, the user profile will be created automatically at Flexopus. After the creation, the local Flexopus administrators can assign the suer profile to the local groups.

USE CASE - Employee leaving (delete through provisioning)
In case an employee is leaving the organization, you usually delete the users profile from your Active Directory or at least remove from the AllFleoxpusUsers group. Through the integration, we receive two requests:

1. User deleted from group AllFlexopusUsers group
2. User has no access to application

The second request will deactivate the user in Flexopus user directory and the user can not log in. The SAML2 Single Sign On will not work, and the user is also set to a deactivated status in Flexopus. Lear in the deletion concept how to automatically delete deactivated users:

TODO - Deletion concept

How can I disable the SCIM Integration?

You can disable the SCIM integration by going to your Azure Active Directory, open the Flexopus SSO / SCIM enterprise application and click on the Stop provisioning button:

Then navigate to Flexopus as an administrator Dashboard > Settings > Integrations and click on the Delete token button.

A popup will open asking you to detach the groups. Enable this option. This will make the current external read only groups to an internal group, so that you can edit them later.

You are done. The SCIM integration is deleted.

Trouble Shooting / FAQ