Documentation
Contact Support

SCIM Configuration

Suggest Edits

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 while maintaining user roles and access across any team or company size.

We now comply with the SCIM 2.0 protocol, which allows compatibility with any identity provider supporting SCIM. Below, we’ll document or link to supported providers, including Okta, Azure AD, Ping, and OneLogin.

SCIM enables the following 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.

Prerequisites

  • You must be on an Enterprise plan to access SCIM. Please contact our sales team to learn about upgrading your plan.
  • You will need Owner permissions to configure SCIM settings.
  • You'll also need to create an API Key to authenticate webhooks from your IDP to FireHydrant. Remember to keep this key somewhere handy.

Enabling SCIM with a supported identity provider

Each identity provider that adheres to SCIM 2.0 standards can connect to our endpoints when creating a custom SAML & SCIM setup. If we are not a verified provider with your identity provider, 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 an HTTP Header with a Bearer API Token using the generated FireHydrant API key.

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.

Okta SCIM

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. 

  1. First, follow the instructions here to set up your organization with Okta SSO.
  2. From within the Okta app, click into Provisioning > Configure API Integration > Enable API Integration. Paste the FireHydrant API token 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. (Optional) 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 access roles.

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. For example, two users cannot share emails that only differ by character casing: [email protected] is treated as being equal to [email protected].

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 in the group and 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:

📘

Note:

If you plan on implementing push groups, we strongly recommend configuring the custom application to perform SAML, SCIM, and push groups to reduce the likelihood of timing issues during app assignment.

  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 next page has you set up SSO. If you are also configuring the app for SSO, 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.
NameName FormatValue
First NameUnspecifieduser.firstName
Last NameUnspecifieduser.lastName
  1. Select that you are an Okta customer adding an internal app and click Finish.
  2. Click into the General tab, then 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 NameValue
Ownerowner
Membermember
Collaboratorcollaborator
Viewerviewer
  1. Save. You can now enable provisioning actions for Create, Update, and Deactivate and 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. This completes Okta SCIM setup.

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 completed the guide to enable Google SSO, follow Steps #1 and #2 here, then skip to Step #4.

  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 to view the SSO URL, Entity ID, and certificate.
    1. If you already have an existing SSO app, enter null values such as http://null when prompted for SAML details
  3. Follow steps 4-20 in this guide.
  4. On the main app page that it takes you to, click into the Autoprovisioning section
  5. Click the button under App Authorization
  6. 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
  7. Paste it into the Access token box and click Authorize.
  8. Click the button under Endpoint URL and enter https://api.firehydrant.io/v1/scim/v2
  9. 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.
  10. Under Status click Turn On. This will start provisioning users that have been scoped for the application.

Entra ID (Azure AD)

📘

Note:

This section assumes that you've already created a SAML app in Entra ID following these instructions.

  1. As an identity administrator in Entra ID, navigate to the SAML app you've created and click into the Provisioning tab. Click into Provisioning again on the next screen.

  2. Click Admin Credentials and enter the following information:

    1. Tenant URL: https://api.firehydrant.io/v1/scim/v2
    2. Secret Token: API key generated following these instructions
    3. Click Test Connection and save.

  3. Click Mappings and click into Provision Active Directory Users

  4. Under Target Object Actions, select the provisioning actions you want Entra to take on users in FireHydrant

  5. Under Attribute Mappings, click Show Advanced Options and click into Edit attribute list for customappsso. This is where we will add our custom roles attribute.

  6. Scroll to the bottom of the next page and, in the empty attribute row, configure it as follows:

    1. Name: roles
    2. Type: String
    3. Multi-Value?: true
      Save at the top and go back to the previous page using the breadcrumbs at the top.

  7. Click Add New Mapping and configure it as follows:

    1. Mapping Type: Constant (note: this you can also use expressions to conditionally define this mapping)

    2. Constant Attribute: role name as defined by the table below:

      Display NameValue
      Ownerowner
      Membermember
      Collaboratorcollaborator
      Viewerviewer

    3. Target Attribute: roles

    4. Click Ok to save your changes.

    5. Click Save at the top.

Using SCIM endpoints without an IDP

Our SCIM provider can be used without SSO, but we strongly recommend implementing it. Otherwise, newly created users in FireHydrant will need to use the “Forgot password” flow to set a new password before logging in. SSO also helps you enforce your IDP's security policies across more applications.

If you still want to configure SCIM without an IDP, the following instructions will help guide you. 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!

Updated 7 months ago