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 an API key within FireHydrant as this will be needed to authenticate. You must have Owner permissions on your organization to utilize API keys. To create an API keys, click here or visit our Creating an API key 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 (https://api.firehydrant.io/v1/scim/v2). Authentication would use Basic Auth as a HTTP Header with a Bearer API Token from the API key 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 Follow the instructions here to set up your organization with Okta SSO.

Configuring SCIM

  1. As a FireHydrant Owner, go to Organization (Settings in the new beta UI) > API keys and click Create API key, 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".

ADVANCED: 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. FireHydrant currently only supports push groups with manual configurations of the SCIM app - see our instructions below:

  1. As an administrator in Okta, go to Applications > Applications > Create App Integration
  2. Select SAML 2.0 and click Next
  3. Enter a name for your app (we recommend FireHydrant) and click Next
  4. This page has you set up SSO. If you are also configuring the app for SSO, go to this page and use the attribute statements listed below. If you will be using a separate SSO app, enter http://null into the SSO URL and Audience URI fields. Click Next once complete.
Name Name Format Value
First Name Unspecified user.firstName
Last Name Unspecified user.lastName
  1. Select that you are an Okta customer adding an internal app and click Finish.
  2. Click into the General tab, click Edit for App Settings, and enable SCIM under Provisioning. Save. The Provisioning tab will be available when the page is refreshed.
  3. Click into the Provisioning tab and configure the SCIM connection as follows
    • SCIM connector base URL: https://api.firehydrant.io/v1/scim/v2
    • Unique identifier field for users: userName
    • Supported Provisoning Actions: All available actions
    • Authentication Mode: HTTP Header
    • Authentication: Enter the API key token created under Requirements to get started Save the configuration. The Push Groups tab will then be available.
  4. (Optional) To support role assignments from Okta, go to Provisioning > To App > Profile Editor and add a Role attribute with the following configuration:
    • Data Type: string array
    • Display Name: Roles
    • Variable Name: roles
    • External Name: roles
    • External Namespace: urn:ietf:params:scim:schemas:core:2.0:User
    • Description (optional): Refers to a user's FireHydrant role.
    • Enum: Enabled
    • Attribute Members:
Display Name Value
Owner owner
Member member
Collaborator collaborator
Viewer viewer
  1. Save. You can now enable provisioning actions for Create, Update, Deactivate and also access a Push Groups tab to configure creating or linking groups between Okta and FireHydrant.
  2. In the SCIM application, go to the Push Groups tab
  3. Click + Push Groups and select the push group type you want to perform
  4. Enter the name of the Okta group and select to either link to an existing team in FireHydrant or create it brand new
  5. Save to start pushing the group. 

Google Workspace

While we do not have a published app with Google Workspace, this guide walks you through repurposing an existing marketplace app to use for for SSO and Provisioning. This is due to a limitation with Google where creating a custom SAML app will not allow you to enable provisioning.

Configuring SSO and SCIM These steps assume that you are setting up SSO from scratch and want to use the same application to manage SSO and SCIM. If you have already followed this guide to enable SSO, follow steps 1-2 under this section and then skip to the Configuring SCIM section.

  1. As a Google Workspace Super Admin, go to Apps > Web and Mobile Apps
  2. Click Add app > Search for apps and locate an existing app that supports Web (SAML) and provisioning, such as Adobe. Click to add it. It will take you to a page where you can view the SSO URL, Entity ID, and certificate.
  • If you already have an existing SSO app, enter null values such as http://null when prompted for SAML details
  1. Follow steps 4-20 in this guide.
  2. On the main app page that it takes you to, click into the Autoprovisioning section
  3. Click the button under App Authorization
  4. As a FireHydrant Owner, go to Organization (Settings in the new beta UI) > API keys and click Create API key, name the token, and copy it
  5. Paste it into the Access token box and click Authorize.
  6. Click the button under Endpoint URL and enter https://api.firehydrant.io/v1/scim/v2
  7. Click the button under Deprovisioning and set your preferences on how to handle accounts in FireHydrant when an app is unassigned from a user or an account is suspended or deleted in Google.
  8. Under Status click Turn On. This will start provisioning users that have been scoped for the application.

Using SCIM public endpoints without an identity provider

Remember to set up an API key to send all requests with a validated API key for the below requests to work. To learn more about API keys click here.

All requests must use our API key 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 9/29/2023