SAML Federation
How Hawcx acts as a SAML 2.0 identity provider
Hawcx implements the SAML 2.0 Web Browser SSO Profile as an identity provider. Your service provider redirects login requests to Hawcx, which authenticates the user and returns a signed assertion to establish the session. See the SSO overview for a visual diagram of this flow.
This page covers the SAML-specific configuration: endpoints, SP-side setup, and SCIM user provisioning.
Hawcx SAML Endpoints
All SAML endpoints are scoped to your tenant and served from sandbox.hawcx.com.
| Endpoint | URL |
|---|---|
| Metadata | https://sandbox.hawcx.com/v1/saml/metadata?project_id={project_id} |
| SSO (passive sign-in) | https://sandbox.hawcx.com/v1/saml/sso?project_id={project_id} |
The metadata endpoint returns a standard SAML metadata document that most service providers can import directly. It includes the signing certificate, entity ID, and SSO binding locations.
What You Configure on the SP Side
Each service provider has its own admin interface for configuring an external identity provider. The general steps are:
- Register the domain you want to federate (e.g.,
sso.yourcompany.com) - Point federation settings at Hawcx's metadata and SSO URLs
- Upload the signing certificate provided by Hawcx (or let the SP fetch it from the metadata URL)
- Set the authentication protocol to SAML
- Configure MFA behavior to accept MFA performed by the federated IdP (Hawcx handles MFA natively)
The specifics vary by SP. See the provider-specific guides below for detailed instructions.
SCIM User Provisioning
SCIM (System for Cross-domain Identity Management) keeps your SP's user directory in sync with Hawcx. Instead of manually creating and removing users in Hawcx, your SP pushes changes automatically.
What SCIM Handles
| Operation | Description |
|---|---|
| Create | New users assigned to the SSO application are provisioned in Hawcx |
| Update | Profile changes (display name, email) sync to Hawcx |
| Deactivate | Removed or disabled users are deprovisioned |
SCIM Endpoint
https://sandbox.hawcx.com/v1/scim/{project_id}/Your SP authenticates to the SCIM API using a bearer token provided by Hawcx support.
Attribute Mapping
At a minimum, map these attributes from your SP directory to SCIM:
| SP Directory Attribute | SCIM Attribute |
|---|---|
| User principal name / email | userName |
| Display name | displayName |
| First name | name.givenName |
| Last name | name.familyName |
emails[type eq "work"].value | |
| Unique object ID | externalId |
The exact attribute names on the SP side vary by provider. See the provider-specific guides for the correct mappings.