Humbol SCIM (System for Cross-domain Identity Management) API allows for real-time employee provisioning from customer’s identity provider.
SCIM API Version: 2.0
SCIM API has been tested to work with these identity providers:
- Microsoft Entra ID (formerly Azure Active Directory)
Prerequisites
- Active contract including SCIM API usage with Humbol Inc
- At least one admin user in customer’s Humbol organization
- If you want to assign Humbol users in Entra ID according to your Entra ID groups, it requires MS Entra ID Premium P1 license for that person who does the integration (so just 1 pc is enough). Otherwise you have to select each person separately or import all (you might have some accounts in Entra ID which you don’t want to import to Humbol).
- You can purchase “Microsoft Entra ID P1” license from here (price in 2024 is 5,6€/month): https://admin.microsoft.com/ (Marketplace -> All Products-> Search all product categories-> “Entra” -> Details)
- Microsoft Entra ID P1 pricing: https://www.microsoft.com/security/business/microsoft-entra-pricing
- Or if you have already some more expensive license (for example Microsoft 365 Business Premium or Microsoft 365 E3) for all, it should also cover this.
- You can purchase “Microsoft Entra ID P1” license from here (price in 2024 is 5,6€/month): https://admin.microsoft.com/ (Marketplace -> All Products-> Search all product categories-> “Entra” -> Details)
Application roles
Humbol application contains these organization level roles which can be controlled via SCIM API:
Admin
Organization admins can invite and remove users from an organization and create new teams and administer all teams in Humbol. Administrators do not see any details of any interaction or action other than via the normal visibility rules.
External admin
External admins have otherwise same rights as organization admins, but its’s visible from their profile that they are external to the organization.
Member
Members can see the organization structure and all interactions and actions, which have “Organization” visibility and their own teams’ interactions and actions. They can administer those teams which they have a team organizer or team supporter role in.
Light Member
Light members mainly use the system only via pre-authenticated links to access those interactions where they are participants or feedback givers. Pre-authenticated links are delivered by email and are person specific and valid only until the discussion has been marked ready. Light members can be team members (but not organizer or supporter) and can participate into actions, but can’t have goals or be action owners. They can also login to Humbol application if they have MS or Google account which corresponds to their email address. Light members do not see any organization level statistics. They don’t see any organization level actions or interactions if they are not part of that team or participate in the specific action or interaction.
External member
External members can see only those teams from the organization which they are part of, plus actions and interactions where they have been registered as participants. They can administer those teams which they have a team organizer or team supporter role in. External members do not see any organization level statistics. They don’t see any organization level actions, goals or interactions if they are not part of that team or participate in the specific action, goal or interaction.
SSO: OAuth 2.0
Administration of permissions and assigned users
Azure Portal
https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview
Google Workspace
https://admin.google.com/u/0/ac/owl/list?tab=apps
Permissions required by the application
- User Profile information
- Read
- Needed for fetching user’s name and profile picture
- Used for all users
- Calendar
- Read & write
- Needed for scheduling and creating calendar events
- Used only by those who book discussions via Humbol
- Offline access
- Needed for 2 way integration for calendar so that you can modify meetings in your calendar and it gets also automatically updated to Humbol
- Used only by those who book discussions via Humbol
- Kept only active as long there are meetings booked via Humbol
Taking SCIM API into use
As Humbol admin login into your Humbol organization: https://my.humbol.app/login.
Go to organization’s API settings page: https://my.humbol.app/settings#apis
On the page there is visible your organization SCIM API url. Copy it.
Create SCIM API token and copy the value. NOTE! The token value is not saved anywhere on the Humbol service, so if you lose it, you should create a new one and remove old one.
Go to your identity provider and change Humbol applications provisioning settings to automatic and use the scim api url and token you acquired earlier.
Disable group provisioning and do the user field mapping automatically or manually. These SCIM attributes are always required:
- userName
- active
- name.givenName
- name.familyName
- emails[type eq ”work”]
- one and only one
Note roles[primary eq “True”] is not required: if role is not given, it can be administered inside Humbol by admin user. If you do map it in Entra ID every user must have precisely one role.
Just running SCIM provisioning does not activate any new Humbol user licences: after provisioning has been run you can add imported people to Humbol organization and assign them to teams from Humbol: https://my.humbol.app/organization/members/invite
Supported SCIM API features
Supported Resources: Users with a role
Schema and supported attributes
See description of supported attributes: https://my.humbol.app/api/scim/Schemas
/Schemas API
Supported methods: GET
/Users API
Supported methods: POST and GET
Supported filters: “userName eq” and ”emails[type eq “work”].value eq”
/Users/<id> API
Supported methods: GET, PATCH and DELETE
Error responses
HTTP error codes are used according to SCIM specification. If error happens there should be a json body telling the reason.
Support
Contact: support@humbol.app