Enabling a SAML integration with Microsoft Entra

What is Entra?

You can use your Entra Active Directory portal to setup a SAML configuration for your organization's Lever account. To learn more, refer to Microsoft's SAML-based SSO setup documentation.

What information do I need?

As with all SAML setups, we will provide Lever's Identifier URL and Reply URL. These are the values for production:

• Lever's SAML endpoint: https://hire.lever.co/auth/provider/saml2/callback
• Lever's audience restriction/identifier: https://auth.lever.co/sp

We need your identity provider end-point URL and your identity provider certificate, public-key format preferred in .txt file.

What does this look like in your Entra portal?

After following the instructions in the Microsoft documentation to add a non-gallery app (see section 1), you can manage the SAML setup by navigating to Microsoft Entra ID > Enterprise applications and selecting the application from the list. Then, under the 'Manage' section you can select 'Single sign-on,' and then select 'SAML.'

How will they configure the integration based on what we send them?

As you can see, the identifier and reply URL are required fields for you to setup on your end.

• Identifier (Entity ID): https://auth.lever.co/sp
• Reply URL: https://hire.lever.co/auth/provider/saml2/callback

Once you set that up, you can send us the login URL and the certificate (see screenshot below).

Mapping attributes

You will need to ensure that your attributes are supported by our SAML configuration. >Lever can support the following user attributes and map them into the Lever user account. None of these are required, but providing ‘fullName’ or ‘firstName’ and ‘lastName’ will allow Lever to provision the users with this information. If no user attributes are set, Lever will use the first part of the email address as userName and not set the user’s first and last name. If no `firstName` is provided, we use the user's email address as their name.

• `name` or `fullName` - used as the user’s full name
• `firstName` and `lastName` - optionally used to generate fullName
• `email` - used as user’s actual email address, defaults to value of `nameID`
• `userName` - used as username, defaults to first part of email address

If the attributes are setup in an unsupported way, you may encounter instances where users are being provisioned via SAML with their email address as their name.

By clicking on the pencil icon next to the User Attributes & Claims section, you can edit what values are being sent in the SAML response. When our SAML request looks for firstName and lastName, it typically corresponds to the given name and surname values in Entra ID by default.

If there is a claim name for 'name', (which would look like http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name), we will look at this value first and use it as the user's name. So, if this claim name is present and mapped to an incorrect attribute like an email instead of a fullname, users will be provisioned into Lever incorrectly. So for Entra ID, it will typically be more successful to use the givenname and surname claims, as we will accept these values as firstName and lastName.

Assigning users and groups

In order to login successfully, your Entra Admin will have to assign users to the application that you have setup.

Supported authentication contexts

In certain circumstances, you may encounter an error suggesting that the authentication context you are using (such as Windows Integrated) does not match the applications requested method. Lever currently supports two authentication methods with Entra ID: Password and Windows. Our <samlp:AuthnRequest> includes a </samlp:RequestedAuthnContext> of Windows or Password. Entra requires a direct match for auth context when a </samlp:RequestedAuthnContext> is included.