Generic SCIM configuration guide

This article guides setting up SCIM user provisioning with any Identity Provider (IdP) that supports SCIM 2.0. This guide focuses on the core principles and steps that apply regardless of the specific IdP you're using.

 

Assumptions

  • You have administrative access to both Hoxhunt and your chosen IdP.
  • You have a IdP environment that supports SCIM 2.0.

 

SCIM authentication token and endpoint 

  • Log in to your Hoxhunt Admin Portal.
  • Create authentication token by navigating to Settings > Automated user provisioning > Create new token.
  • Hoxhunt SCIM endpoint URL is https://app.hoxhunt.com/services/scim.

 

Obtaining Hoxhunt's SCIM schema

    • You can retrieve Hoxhunt's SCIM schema by sending a GET request to https://app.hoxhunt.com/services/scim/schemas.
    • For example: 
      GET https://app.hoxhunt.com/services/scim/schemas
       Authorization: Bearer <your_scim_token> 
    • Examine the JSON response. This is the definitive SCIM schema for Hoxhunt. If your IdP requires a static schema file, save these responses.
    • Pay close attention to:
      • Attribute data types.
      • Schema URIs for extension attributes.
      • Case sensitivity (or lack thereof) where indicated.
    • Find example requests for creating, updating and deactivating users from Example SCIM requests article. 

 

IdP configuration

Access your IdP's administration console:

  • Log in to your IdP with an account that has administrative privileges.

Locate the SCIM Integration or Provisioning Section:

  • Most IdPs have a specific section for configuring SCIM integrations. Look for options like "Provisioning," "SCIM Integration," "Application Provisioning," or similar terms.

Create a New SCIM Application or Connection:

  • Add a new application or connection specifically for Hoxhunt.
  • Select "SCIM 2.0" as the provisioning protocol.

Configure the SCIM Connection:

  • Base URL (or Tenant URL): Enter the Hoxhunt SCIM endpoint URL: https://app.hoxhunt.com/services/scim
  • Authentication:
    • Select "Bearer Token," "API Key," or the equivalent authentication method supported by your IdP.
    • Enter the SCIM token you generated in Hoxhunt Admin Portal to the appropriate field (e.g., "Token," "API Key," "Secret").
    • Note: Some IdPs might require you to specify the header name for the token (e.g., Authorization).
  • Test Connection: Most IdPs provide a "Test Connection" or "Verify" button. Use it to verify that your IdP can successfully connect to Hoxhunt SCIM endpoint using the provided token. Troubleshoot any connection issues before proceeding.

Configure Attribute Mappings:

  • Unique Identifier: The emails[type eq "work"].value field is unique in Hoxhunt. IdPs are able to use this field as a pre-provisioning check to determine if a User resource exists. For example, /Users?filter=emails[type+eq+"work"].value+eq+"someone@hoxhunt.com"
  • Active Status Mapping: Map your IdP's user status (e.g., "active," "inactive," "enabled," "disabled") to the Hoxhunt active attribute (true for active, false for inactive).
  • Please refer to the Hoxhunt SCIM attributes article for a comprehensive list of supported target attributes and their definitions.

Enable Provisioning:

  • In many IdPs, you need to explicitly enable provisioning for the Hoxhunt application. This might involve toggling a switch, selecting a provisioning mode (e.g., "Sync users," "Push users"), or configuring a provisioning schedule.

Define Scope of Provisioning (Target Users/Groups):

  • Specify which users or groups in your IdP should be provisioned to Hoxhunt. This is typically done by assigning users or groups to the Hoxhunt application.
  • Start with a small test group to avoid unintended consequences.

 

Testing and monitoring 

  • Provision Test Accounts:
    • Create test accounts in your IdP that match the criteria of your provisioning scope.
  • Verify Provisioning in Hoxhunt:
    • Verify that the test accounts are correctly provisioned in Hoxhunt.
    • Check that all attributes are correctly mapped and transformed.
  • Test Updates:
    • Update the attributes of the test accounts in your IdP and verify that the changes are reflected in Hoxhunt.
  • Test Deactivation:
    • Deactivate the test accounts in your IdP and verify that they are deactivated in Hoxhunt.
  • Review IdP Logs:
    • Examine your IdP's provisioning logs for any errors or warnings.
  • Monitor SCIM Activity:
    • Regularly monitor the SCIM activity logs in both your IdP and Hoxhunt to identify and resolve any provisioning issues.

 

Generic tips for any IdP

  • Start Simple: Begin by provisioning a small set of users with a minimal set of attributes. Gradually expand the scope and complexity of your provisioning configuration.
  • Monitor Logs: Regularly monitor the logs in both your IdP and Hoxhunt to identify and resolve any issues.
  • Contact Support: If you encounter any difficulties, don't hesitate to contact the support teams for your IdP and Hoxhunt.

This generic guide should provide a foundation for setting up Hoxhunt SCIM user provisioning with any IdP that supports SCIM 2.0. Remember to consult the specific documentation for your IdP and Hoxhunt for detailed instructions and troubleshooting tips.

 

Useful links

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request