• Summary
• SAML app integrations
• IdP-agnostic SAML integration
• Create app integration
• Set SP Metadata URL
• Set ACS URL
• Set SP Login URL
• Map SAML attributes
• Other SAML integration settings
• Share configuration with Millie
• IdP Metadata
• Email Domains
• Test integration

Summary

If you are an IT person, this document will help you integrate Millie into your company's SAML SSO setup. For a more general introduction to Millie SSO and provisioning, visit this page.

Millie's SSO functionality is implemented with SAML 2.0. This is the only SSO technology that Millie supports.

SAML app integrations

When connecting Millie with your IdP, you can save time by using a pre-configured app integration, which you will find in your IdP's app catalog. The following IdPs offer pre-configured Millie integrations:

• Okta

If you use a different IdP, you must create your own custom integration. Millie offers IdP-specific SAML integration instructions for the following IdPs:

• Azure

Others can be configured with the more general instructions below. Millie SSO has been tested with Okta, Azure, and Google, but it should work with any IdP that supports SAML 2.0. Only one IdP can be associated with your Millie account.

IdP-agnostic SAML integration

Create app integration

First, you must create a new app integration in your IdP. Typically you will do this in an Applications page within the IdP console. If you are prompted to select an app from the IdP's catalog, bypass that and create your own 'custom' app instead.

When prompted:

• Set the application type to SAML 2.0, if you get the chance. Not every IdP asks this question directly.
• Set the name of the app to Millie.
• Attach the Millie logo to your app, for easy recognition by your users. You can download the Millie logo here:

Set SP Metadata URL

Now login to Millie as a company admin and navigate to the SSO page at Settings / SSO:

This page displays SSO and provisioning details that are specific to your company. Find the SP Metadata URL, which looks something like:

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

This address serves SAML metadata that describes Millie's SSO requirements. IdPs use this URL as a unique identifier for the SP, which in this case is Millie.

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

• Identifier
• Entity ID
• Audience URI

Set ACS URL

Now find the ACS URL in the SSO page:

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

ACS stands for Assertion Consumer Service. This is the address to which your IdP POSTs the SAML assertion that approves an employee's login. Add this to your integration as well. The integration field may have one of these names:

• ACS URL
• Reply URL
• Single sign-on URL (not to be confused with Sign-on URL in Azure)
• SP sign-in address

Set SP Login URL

You will also find an SP Login URL in the SSO page:

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

This is a Millie API endpoint that sends the user to the IdP for authentication. Most IdPs do not use this value, but Azure rejects SP-initiated logins unless they come from this URL, and yours might too. The field in your integration might have this name:

• Sign-on URL (not to be confused with Single sign-on URL in Okta)

Map SAML attributes

Next, you must map your IdP's employee data to specific SAML attributes, for consumption by Millie. These fields are required:

• id or _id This attribute identifies the employee within your company. It is often mapped to their email address, but it can also be an employee ID. It must be unique within your company. When mapping attributes, Google Identity fails with a vague message if you name the attribute id. For this reason, you can also name it _id.
• email This is the employee email address. It must be unique within your company.
• firstName This is the employee's given name.
• lastName This is the employee's surname.

The following fields are optional:

• profileImage A URL string that references the employee's profile image. Your employee can also set or replace this image on their own, within the Millie app.

Other fields will be ignored by Millie.

Note that email, firstName, and lastName are updated in the Millie database every time SAML is used to login. profileImage is set during the first login, if it is mapped; it is not updated during subsequent logins.

Other SAML integration settings

Other integration fields can typically be left blank, or left with their default values.

Share configuration with Millie

When your integration is complete, you must share your IdP metadata and your company's email domains with Millie.

IdP Metadata

Your IdP will produce SAML metadata that describes your configuration. Most IdPs provide a URL that serves this metadata. The URL may be labeled with one of these names:

• Identity Provider Metadata URL
• App Federation Metadata URL

If your IdP provides it, please copy this URL and mail it to tech@milliegiving.com, along with your company name.

Some IdPs allow you to download the metadata as a file, instead of hosting it themselves, at a URL. If that is the case, email the SAML text to Millie, with your company name. Millie will host the metadata and produce a URL.

After we update your account, you will find the URL in the SSO page, within the read-only IdP Metadata URL field.

Email Domains

Finally, check the Email Domains line in the SSO page. Millie uses the employee's email address as a unique SSO identifier, and the domain in that address is used to determine the company (and therefore the IdP) to which the employee belongs. No employee can login with SSO unless their email domain is listed here.

If your company is new to Millie, this entry will be blank. To add domains, email tech@milliegiving.com. You can add as many domains as you like, but all domains must be owned by your company. Gmail addresses can never be used with Millie SSO.

After receiving IdP metadata and email domains, we will update your Millie account, and then notify you.

Test integration

When you see that the IdP Metadata URL and Email Domains fields are set in the Millie SSO page, you are ready to test. Assign your new Millie app integration to one or more users within your IdP, and perform both IdP-initiated and SP-initiated logins.

If you run into trouble, please contact tech@milliegiving.com. We will be happy to help!