User provisioning with SCIM

SCIM & FireHydrant

System for Cross-domain Identity Management ( SCIM ) ensures the highest level of security for managing user identity and provisioning. SCIM will allow for user onboarding automation with maintaining user roles and access across any team or company size. We now comply with SCIM 2.0 protocol allowing compatibility with any identity provider supporting SCIM. Below, we’ll document or link to supported providers, including Okta, Azure AD, Ping, and OneLogin.

In this article, we will cover the user provisioning actions you can perform with FireHydrant’s SCIM and provide further documentation on how to incorporate your identity provider.

User provisioning actions

Add/Deactivate users : All users can easily be added to FireHydrant with their correct roles and permissions. This includes the teams or groups they belong to.
Update users : Changing user access in your identity provider automatically persists into FireHydrant to maintain the most updated roles and access for all users.
Create/Deactivate Groups : User groups can be pushed from your provider and assigned to match teams in FireHydrant.

In addition to the above, all users and groups can be queried to see complete lists.

Requirements to get started

Note: You must be on an Enterprise plan to access SCIM. Pleasecontact our sales team to learn about upgrading your plan.

Before you get started, make sure to create a Bot User within FireHydrant as this will be needed to authenticate. You must have Owner permissions on your organization to utilize Bot Users. To create a Bot Users, clickhere or visit ourCreating a Bot User documentation to learn more.

Using SSO with SCIM

Our SCIM provider can be used with or without SSO. When using an identity provider with SCIM you are not required to use SSO, but doing so helps provide easy login for new users. This prevents newly created users in our FireHydrant application from having to use “Forgot password” to set a new password before logging in.

To learn more on setting up SSO clickhere. If you are not using SSO or an identity provider, and would like our public endpoint for SCIM, please scroll to the bottom of this section for “Using SCIM public endpoints without an identity provider.”

Enabling SCIM with a supported identity provider

Each identity provider that adheres to SCIM 2.0 standards will be able to connect to our endpoints when creating a custom SAML & SCIM setup. If we are not a verified provider with your identity provider, then you’ll need to create a custom app to point to FireHydrant via SAML.

From here you can set up a custom SCIM configuration to point to our SCIM Base URL (api.firehydrant.io/v1/scim/v2). Authentication would use Basic Auth as a HTTP Header with a Bearer API Token from the Bot User previously created in the requirements section. Then you can set provisioning parameters to specific user attributes within your provider. To see those user attributes that you can provision in our endpoints take a look at our developer documentation.

To learn more about specific identity provider configuration, please scroll to the sections below.

Okta

These instructions assume that you are either:

Setting up SAML for the first time with FireHydrant, or
You plan on setting up a combination SAML + SCIM app for FireHydrant, reassigning your users to that for login, and removing your old SAML app

If you plan on keeping an existing SAML app and having the SCIM configuration separate we will include additional instructions in-line below.

As your Okta admin, first go to the Applications tab to start a new application. To do this you’ll need to click Create App Application and follow these instructions:

Select SAML 2.0 and click Next.
Name your app (recommendation: FireHydrant) and hit Next.
You’ll need to configure SAML settings with FireHydrant SSO which you can learn to do here.
If you plan on keeping an existing SAML app for FH, enter “http://null” for the values, skip step 4, and flag the “Do not display application icon to users” checkbox on the “General” tab after you’ve created the application.
Under Attribute statements be sure to fill out a two lines of fields:
Name field as firstName with a value user.firstName
Name field as lastName with a value user.firstName
Click next at the bottom of this page to move to step 3 of the Okta process.
On step 3, select “I'm an Okta customer adding an internal app” and select Finish.

This process has finalized SAML & SSO for the app. Next we will configure SCIM with these steps:

Under the new FireHydrant integration click the General tab to edit the App Settings section.
In edit mode check off SCIM under the provisioning field and click save which will add a new Provisioning tab to the integration.
Click the new Provisioning tab that appears and on the left navigation select Integration.
SCIM connector base URL should include this URL: https://api.firehydrant.io/v1/scim/v2
Unique identifier field for user should include the value: userName
Supported provisioning actions should be selected depending on the provisioning use cases you would like to use.
Authentication Mode should be selected as HTTP Header.
The Authorization field should include the Bot User Token you created within FireHydrant here.
Save these settings.
On the left navigation click To App.
Make sure Create Users, Update User Attributes, and Deactivate Users are all enabled.

Within this section scroll to the Attribute Mappings. You will only need user.firstName, user.lastName, and user.email. You will create the roles attribute in the below section to be able to manage roles.

Set up Okta to manage roles

Go to Directory > Profile Editor and locate the SCIM app that was created. Click into it.
Click Add Attribute and configure a roles attribute with the following configuration:
Display name: how attribute should appear in Okta
External name: roles
External namespace: urn:ietf:params:scim:schemas:core:2.0:User
Enum: Check the box for “Define enumerated list of values” and enter the following:

Owner > owner
Collaborator > collaborator
Member > member 5. Then click Save.

How to push groups into FireHydrant as Teams

FireHydrant supports Okta push groups, allowing you to push the memberships of a group in Okta into FireHydrant. Only employees who are in the group and are also assigned to the FireHydrant app in Okta will be pushed.

In the SCIM application, go to the Push Groups tab
Click + Push Groups and select the push group type you want to perform
Enter the name of the Okta group and select to either link to an existing team in FireHydrant or create it brand new
Save to start pushing the group.

Assigning Users to the new custom SCIM application in Okta
As you begin to assign users to the FireHydrant application in Okta via Assignments , you will see the users populate within FireHydrant.com. Updating first name, last name, email, roles, and groups will all be automatically provisioned into FireHydrant.

Note: For updating user actions, we only accept PUT requests. Okta may default to using PATCH on setup but this can be reformatted. You can reach out to Okta support if this issue happens so you can update the route. Feel free to visit their supporthere.

Note: FireHydrant does not support case-sensitive emails. Please ensure that your users' emails are case-insensitive. That is, two users cannot share emails that only differ by character casing, e.g., "JANICE@yourcompany.com" is treated as being equal to "janice@yourcompany.com".

Using SCIM public endpoints without an identity provider

Remember to set up a Bot User to send all requests with a validated Bot Token for the below requests to work. To learn more about Bot Users clickhere.

All requests must use our Bot Toke made with the following headers:

--header 'Content-Type: application/scim+json; charset=utf-8' \

--header 'Accept: application/scim+json'

You can make the following requests to our SCIM API:

Fetch a list of Users or single User
Create, Update, or Delete a new User object
Fetch a list of Groups or single Group
Create, Update, or Delete a new Group object

To see each request in depth feel free to visit our API support documentation, particular the SCIM section.

You can also easily download these requests when visiting our Postman Collectionhere.

Once Users are created and have access established, they can be directed to login toFireHydrant.com.

SSO Enabled : Users should be directed to click Sign in with SSO. The login process for these new users will redirect them to verify with the identity provider. Once the user validates with the identity provider they will be automatically granted access to FireHydrant.

SSO Not Enabled and password is not defined : If your admin used the public endpoint or identity provider to create new users and did not pass in a user’s password to our POST route, the FireHydrant app will automatically create a hardened password for the user on our backend. Newly created users will need to follow these instructions to login if SSO is not enabled:

The new user will need to visit ourForgot Password page.
From here the user will need to enter their email used to create their account and reset their password.
Once the user resets their password they will be able to login as normal.

SSO Not Enabled and password is defined: The password sent on user creation, by your admin, can be used to login with email and password atFireHydrant.com.

Additional Identity Providers

For any identity providers not covered here, you can find out more about adding SCIM and SAML by accessing the provider’s documentation.

Azure Ad

Ping

OneLogin

SCIM: https://developers.onelogin.com/scim
SAML: https://developers.onelogin.com/saml

Support

If any issues persist during setup, please reach out to FireHydrant supporthere for further help!