Provisioning and Deprovisioning Identities with SCIM in Microsoft Active Directory

Setup the AD absence.io app

Sections in this article

1. Maintain SCIM Provisioning & Details of Technical Steps
2. Provision Users to absence.io from Active Directory
3. Troubleshooting & known Issues
4. Setup SCIM in absence.io & connect to Active Directory

Please note, that it might be difficult for us to help you on some issues. This is due to the diversity of Active Directory setups, licenses, the access restrictions in place and the sensitivity of the data. 
We kindly advise that a Microsoft Azure Expert can help you on your end if needed. We are of course here to help you with problems as far as possible!

If you are interested in the technical details - further down you find troubleshooting steps & technical  infrastructure of our Azure Active Directory SCIM integration.

Setup SCIM in absence.io & connect to Active Directory

Summary

1. Given: a.io account with [e-mail] + any number of [e-mail] user profiles
2. company connect with in a.io china create instance
3. create custom app in AD
4. create groups in AD for AD identities assign AD User Identities to this group within the custom app
5. Existing a.io users with "[e-mail]" in AD "username" field -> SSO for users active, included in provisioning cycles
6. Non existing absence.io users -> created as inactive in absence.io, no invite send out

Create a non Gallery App

1. Connect your Office 365 account.
2. In integration settings in absence.io retrieve your SCIM credentials (URL & Secret)
3. Create a custom "Non Gallery App"
   1. Go to your Microsoft Azure Portal
   2. Go to Enterprise applications
   3. Click on "New Application"
   4. Create your own "Non-Gallery-App

Activate Provisioning in the non-gallery App

1. In the app you just created, go to "Provisioning" on the left 
   1. enable automatic provisioning (cannot be set to manual again, only deactivated)
   2. test the connection, if it fails, check your SCIM credentials
2. Setup a notification email as needed
3. Scroll down, enable Automatic Provisioning and Save
4. The final step may need some patience - wait a few minutes (and up to an hour) on the absence.io user list to see your identities being created from your directory

Provision Users to absence.io from Active Directory

• A user can be added to the “non gallery app“ directly or through a group and will then be provisioned.
• Through several "non gallery apps" and user assignment to these apps, AD Admins can create different scopes of provisioning to one or multiple absence.io accounts.
• When the user is modified in Active Directory by being removed from the provision group, or deactivated, then they get deactivated/deleted from absence.io.
  • absence.io might therefore not now why a user is removed from an absence.io instance. How your group and app memberships are setup in active directory is out of our hands. 

Already existing identities in Active Directory

When you already have some user identities setup in your active directory and absence.io instance, these users identities can be connected for provisioning purposes. 

For that to work, the users emails on absence.io must match the active directory "username" field, which is an email like value. When the integration is setup & emails are matching, the users at absence.io are kept and their absence.io user profile is now connected with the active directory identity, therefore also activating SSO for that person.

All the absence.io user properties will be retained, so vacation, absences, time entries and allowances will not be affected by connecting a users to O365 or an identity manager (like active directory).

Exception: the email matches, but the user is already integrated with a different o365 account. This will generate an error visible under SCIM logs in the absence.io settings and the active directory custom app provisioning logs.

All other not existing users in absence.io will be provisioned into absence.io as inactive once the integration connection is setup. 

Email address changes & sync

In case a active directory user (ie. identity) email address (UserPrincipleName) is changed, the correlating absence.io users email address will also change. This is true for any initially provisioned user into the absence.io instance. To make sure this works, please checkout the attribute mappings of users in the non-gallery enterprise app (see screenshot below). The attribute ObjectID must be mapped to ExternalID attribute instead of the mailNickname attribute.

However for users, who where already created in the absence.io instance and then connected to their provisioning AD identity, we will not change the corresponding absence.io users's email address.

Troubleshooting & known Issues

• Admin who ran Connect Company is no longer an admin or no longer part of the Active Directory. In this case a new admin has to redo the Company Connect on absence.io.
• Admin is not added to the non gallery app as a user
• All users need a email on AD to be created or linked in absence.io. Make sure your users have a correct email in the "userName" field in active directory.
• Provisioning might take a while (up to 40 Minutes). So it can take some time before users show up in absence.io user list. This is due to Microsoft Active Directory default behaviour.
• For old azure app users before our December 2019 release -> reconnect the O365 application in absence.io settings
• You have to have the O365 Company Integration activated to enable SCIM in absence.io
• If you have errors on some users in provisioning, try to renew your Office 365 admin consent.

Maintain SCIM Provisioning & Details of Technical Steps

For a detailed explanation please visit the Microsoft Help for active directory here.

Here you can see how to report on your provisioning in Active Directory.

Technical Documentation

1. Create a SCIM endpoint in absence.io & connect to a Microsoft Azure Active Directory Non-Gallery App with the created SCIM credentials. May have to connect O365 on organisation level & give admin consent. This is explained above.
2. AD sends a request to absence.io O365 SCIM endpoint
   1. AD starts a provisioning cycle and starts requesting the a.io SCIM endpoint
   2. The requests include the userName property. That property is treated by absence.io as the user email, which is required for every user on absence.io.
   3. Other properties that come from the request are the users first and last name.
   4. Additional properties are collected in order to fulfill the SCIM protocol, but are never displayed anywhere in the app. Those being externalId and contact email (not used as source of identity).
3. absence.io sends a request to Microsoft Graph API /v1.0/users endpoint
1. Needed so absence.io has access to the id property, which is required for single sign on.
2. The userName property received on the original request is used to match userPrincipalName, giving us the remaining data from the provisioned user that was not included in the original provision payload.
4. With all the information in place, the user is then activated and saved to the absence.io database.

Because of Step 3, any company setting up automatic user provisioning must do the Company Connect operation. In case it has already been done before 2020 then it needs to be done again (disconnect, then reconnect). This is important because it will allow the app to have access to the Microsoft Graph API on behalf of the admin who ran the operation. Without this permission, it is impossible to automatically enable the authentication for a provisioned user.