🔑

Integrating Millie SCIM with any IdP

Summary

If you are an IT person, this document will help you integrate Millie into your company's SCIM provisioning setup, using any IdP. For a more general introduction to Millie SSO and provisioning, visit this page. For SCIM help with a specific IdP, visit one of these pages:

Enable SCIM in Millie app

First, a flag must be set in the Millie app to enable SCIM. Login to Millie as a company admin and navigate to the SSO page at Settings / SSO:

image

In the provisioning section, a badge next to Provisioning (SCIM 2.0) reads ACTIVE or OFF to show the status of the SCIM flag. Contact Millie at tech@milliegiving.com to have it enabled.

Create SAML app integration

Next, you must add a custom Millie SAML app integration to your IdP. You will then modify and extend this integration in the steps below. At present, there is no pre-configured integration that connects to SCIM at Millie.

If you already have an integration, you may continue. Otherwise, use Millie's IdP-agnostic SAML setup guide to create one, test it, and then return here.

Millie SCIM has been tested with Okta and Azure, but it should work with any IdP that supports SCIM 2.0. Only one IdP can be associated with your Millie account.

IdP-agnostic SCIM integration

Enable SCIM in integration

Login to your IdP's admin console and select your Millie SAML integration. You should see an integration properties page of some sort. If there is a provisioning tab within this page, select it. Now click enable SCIM or something similar to reveal a set of SCIM-specific input controls.

Set Base URL

Return to the Millie SSO page and locate your company's Base URL, which resembles:

https://app.milliegiving.com/saml/COMPANY

This is the base path for Millie's SCIM API, which your IdP will use to write and read employee data.

You must add this URL to your integration; unfortunately, different IdPs attach different names to this and other fields. Your IdP might use one of these names, or something similar:

  • SCIM connector base URL
  • Tenant URL

Set OAuth Bearer Token

Now find the OAuth Bearer Token in the SSO page. It is a UUID, formatted like:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Millie uses this value to authenticate incoming SCIM requests. You must add this to an integration field, which may be named something like:

  • Bearer Token
  • Secret Token
💣
Caution: anyone with this token can send SCIM request on your company's behalf! You should protect it the same way you would protect a password.

Map SCIM User attributes

Fields in your IdP employee data must be mapped to SCIM attributes, for use by Millie. Your IdP has likely mapped these attributes already, and the default mappings should be correct.

You may delete attributes you do not want to share with Millie, but certain mappings are required, and must not be deleted. These include:

  • userName
  • name.givenName
  • name.familyName
  • active (when this becomes false the employee will be “deprovisioned”/”deactivated”)
  • One or more fields relating to the employee email address

SCIM represents email addresses as objects within an emails array, and one of these must have a type value that is equal to 'work'. Unfortunately, different IdPs represent this mapping in different ways. The entire construction might be represented with a single SCIM filter expression, such as:

  • emails[type eq "work"].value

or it might be represented with separate email and emailType fields, or perhaps another way altogether.

Again, you do not have to delete any of the mappings! The Millie app will ignore SCIM data it does not need.

Disable SCIM User deletion

You should find controls in your integration that specify the type of SCIM User operations that are allowed. You should allow:

  • User creation
  • User updates
  • User deactivation

You should not allow users to be deleted. Millie does not support SCIM User deletion, AKA: “hard delete”s. For deprovisioning/deactivation, Millie relies on “soft delete”s, which happens via the active attribute.

Disable SCIM Groups

You should also find controls that manage SCIM Group operations. Millie does not support SCIM groups. If there are separate checkboxes for different Group operations, uncheck all of them:

  • Push Groups
  • Import Groups

If you see a control that enables Group functionality as a whole, disable it.

Start provisioning

Finally, it may be necessary to explicitly start the provisioning process. This may be done with a Start provisioning button, a Provisioning Status control, or something similar.

You can test your provisioning setup by creating or editing employees in your IdP, and then checking for the updates in the Millie Employees page, found at Settings / Employees within the admin menu:

image

As always, if you need help, please contact us at tech@milliegiving.com!