Search Results

Start for free

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. Please contact 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, click here or visit our Creating 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 we strongly recommend implementing it. This prevents newly created users in our FireHydrant application from having to use “Forgot password” to set a new password before logging in and also helps you enforce your IDP's security policies across more applications.

To learn more on setting up SSO click here. 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, follow steps 1-3 under Configuring SSO and all of the steps under Configuring SCIM. 

Configuring SSO

As an Okta super admin, first go to the Applications tab to start a new application. Then:

  1. Click Browse App Catalog
  2. Search for the FireHydrant app, click into it, and click Add Integration
  3. Name your app (recommendation: FireHydrant) and hit Next. This will drop you onto the Assignments page.
  4. Click into Sign On and go to View SAML setup instructions
  5. As a FireHydrant Owner, navigate to FireHydrant and go to Account Settings > Single sign on and enter the IdP Login URL, IdP Issuer, and IdP X509 Certificate as presented in step 4. Optionally add a domain for SP-initiated logins.
  6. Enable SSO and save your configuration. This completes the setup for SAML 2.0 SSO.

Configuring SCIM

  1. As a FireHydrant Owner, go to Account Settings > Bot tokens and click Create bot user, name the token, and copy it
  2. From the app in Okta, click into Provisioning > Configure API Integration > Enable API Integration. Paste the token from step into into the API token field. You can optionally choose to import groups at this point.
  3. Click Test API Credentials to verify the connection and Save.
  4. Enable Create, Update, and Deactivate actions.
  5. If your SCIM app is separate from SSO, go to General and select Do not display application icon to users.

Assigning Users to the new application in Okta
You can now start assigning users to link their Okta identities to existing accounts in FireHydrant or create new ones from the Assignments tab. We recommend using Okta groups aligned with the roles you wish to assign. Learn more about our roles here.

Updates to these fields can be made over SCIM: first name, last name, email, roles, and groups

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 support here.

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".

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.

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

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 click here.

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 Collection here.

New User Sign-in Flow

Once Users are created and have access established, they can be directed to login to FireHydrant.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:

  1. The new user will need to visit our Forgot Password page.
  2. From here the user will need to enter their email used to create their account and reset their password.
  3. 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 at FireHydrant.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

Support

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

Last updated on 5/24/2023