Deepfactor can integrate with SSO providers that support SAML 2.0 or OpenID Connect (OIDC) to ensure access to Deepfactor is managed centrally via the SSO provider.
Deepfactor supports the following two user provisioning modes:
- System for Cross-domain Identity Management (SCIM) provisioning
- Just in time (JIT) provisioning
System for Cross-domain Identity Management (SCIM) User provisioning #
In this mode, Deepfactor will automatically sync users from your SSO provider using SCIM protocol.
The SCIM user sync behavior is summarized below:
- Deepfactor will sync users only from groups that have a corresponding team in Deepfactor. The group name in your SSO provider should match the team name in Deepfactor to ensure users are synced.
- The org admin has to create teams in Deepfactor with the same name as groups in your SSO provider for users to be synced. Deepfactor will not automatically create teams.
- While Deepfactor supports integration with multiple SSO providers, if SCIM is enabled, only one active SSO integration is allowed.
#
Just in time (JIT) User provisioning #
In this mode, Deepfactor automatically provisions an account for users when they log into Deepfactor through SSO for the first time. If a local password account already exists for that user (email), it is converted into an SSO account and such users will not be able to login to Deepfactor using their local password until the SSO integration is active.
Deepfactor provides two ways of managing team memberships for users who are created using JIT provisioning.
- Deepfactor managed
In this mode, the organization admin can decide the initial team membership at the time of integrating with the SSO and pick the default team/role for new SSO users. The admin can also update team/role memberships of users using Deepfactor’s user management module. You can read more about it in the following article:
Organization and Teams - SSO provider managed
In this mode, the team-role combinations can be passed from the idp using a custom claim (df_access) in the SSO token. You can read more about it in the following article:
Configure team memberships and roles from idp
#
Setup SAML for SSO with Deepfactor #
Setting up SAML requires configuration in both your identity provider and Deepfactor. Please add the following details in your idp to establish trust with Deepfactor.
| Detail | Value |
|---|---|
| Entity ID | urn:deepfactor:saml |
| ACS URL | https://{host_name}/api/auth/v1/saml/acs |
The Entity ID is the URL that uniquely identifies Deepfactor as a SAML service provider.
The Assertion Consumer Service (ACS) or Reply URL is the endpoint on the Deepfactor portal that listens to requests from your identity provider to enable communication between users and Deepfactor.
Ensure the following attributes are mapped in your SSO provider.
| Attribute | Required/Optional | Description |
|---|---|---|
| first_name | Required | First name of the user |
| last_name | Required | Last name of the user |
| Required | Email address of the user | |
| df_access | Optional | Team-Role combinations. This is required only if you have opted to manage team memberships from idp. |
Once you have configured the above in your SAML SSO provider, navigate to Integrations (from left sidebar) and Identity Provider on the Deepfactor portal. Click on ‘Add SAML 2.0’ and enter the following information obtained from your SSO.
Add SSO integration
| Detail | Required/Optional | Description |
|---|---|---|
| Name | Required | Enter a name to recognize the SSO provider on the Deepfactor portal |
| Metadata URL | Optional | Metadata URL obtained from the SSO provider, if available |
| Signing Certificate | Required if metadata URL is not available | Signing certificate to establish trust with the SSO provider |
| Protocol Binding | Required if metadata URL is not available | POST or REDIRECT |
| Entity Id | Required if metadata URL is not available | Entity Id obtained from the SSO provider |
| Sign In URL | Required if metadata URL is not available | Sign In URL obtained from the SSO provider |
| User provisioning | Required | SCIM or JIT |
| Manage team memberships | Required | You can decide to manage user’s team and role configuration from the Deepfactor portal or directly from the idp. For the latter, you will need to pass df_access claim in the SSO token |
| Default Role | Required | Any new user who logs into Deepfactor using this SSO will be assigned this role. If you select Admin, the user will have admin access to all teams. |
| Default Team | Required | Any new user who logs into Deepfactor using this SSO will be added to this team. |
Once you enter these details, the SSO integration will remain in the unverified state until at least one user successfully logs in via the SSO, which would ensure that the SSO is configured correctly. If you have selected SCIM for user provisioning, then you will get the following details after successful integration. Please enter these details in the SCIM app of your SSO provider.
Setup OIDC for SSO with Deepfactor #
Deepfactor also supports OIDC for signing into Deepfactor. Please add the following details in your SSO provider to establish trust with Deepfactor.
| Detail | Value |
|---|---|
| Callback/Redirect URIs | https://{host_name}/oidc/authorization-code/callback |
| OAuth Grant Type | Authorization Code |
Ensure the following attributes are mapped in your SSO provider.
| Attribute | Required/Optional | Description |
|---|---|---|
| given_name | Required | First name of the user. Generally present by default. |
| family_name | Required | Last name of the user. Generally present by default. |
| Required | Email address of the user. Generally present by default. | |
| df_access | Optional | Team-Role combinations. This is required only if you have opted to manage team memberships from idp. |
Once you have configured the above in your OIDC SSO provider, navigate to Integrations (from left sidebar) and Identity Provider on the Deepfactor portal. Click on ‘Add OIDC’ and enter the following information obtained from your SSO.
| Detail | Required/Optional | Description |
|---|---|---|
| Name | Required | Enter a name to recognize the SSO provider on the Deepfactor portal |
| Client Id | Required | Client Id obtained from the SSO provider |
| Client Secret | Required | Client Secret obtained from the SSO provider |
| Metadata URL | Optional | Metadata URL obtained from the SSO provider, if available |
| Authorization endpoint | Required if metadata URL is not available | |
| Token endpoint | Required if metadata URL is not available | |
| User info endpoint | Required if metadata URL is not available | Entity Id obtained from the SSO provider |
| User provisioning | Required | SCIM or JIT |
| Manage team memberships | Required | You can decide to manage user’s team and role configuration from the Deepfactor portal or directly from the idp. For the latter, you will need to pass df_access claim in the SSO token |
| Default Role | Required | Any new user who logs into Deepfactor using this SSO will be assigned this role. If you select Admin, the user will have admin access to all teams. |
| Default Team | Required | Any new user who logs into Deepfactor using this SSO will be added to this team. |
Once you enter these details, the SSO integration will remain in the unverified state until at least one user successfully logs in via the SSO, which would ensure that the SSO is configured correctly. If you have selected SCIM for user provisioning, then you will get the following details after successful integration. Please enter these details in the SCIM app of your SSO provider.
Verify SSO integration #
Once you enter the SSO configuration details in the Deepfactor portal, the SSO integration will remain in the unverified state until at least one user successfully logs in via the SSO, which would ensure that the SSO is configured correctly.
SSO integration in unverified state
#
Disable SSO integration #
You can decide to disable the SSO integration from the Deepfactor portal. Once disabled, users will not be able to login using the SSO. However, users that had local passwords can login to Deepfactor using their password after the SSO is disabled. You can decide to re-enable the SSO integration from the Deepfactor portal, if required.
Disable SSO integration
#
Delete SSO integration #
You can decide to delete the SSO integration from the Deepfactor portal. Once deleted, users will not be able to login using the SSO. Please note this is permanent and you cannot recover the SSO integration and you will need to reconfigure the SSO, if required.
Delete SSO integration
Disable password authentication #
Once you have successfully integrated your SSO with Deepfactor, you can disable password authentication to ensure every user logs into Deepfactor via SSO. In order to ensure you do not get locked out of your Deepfactor account, you can disable password authentication only when you have at least one active SSO integration which is verified (at least one user has successfully logged in via the SSO).
Please note that you can still get locked out of your Deepfactor account if the SSO configuration is deleted/edited from the SSO provider portal and password authentication is disabled. In such scenarios, please reach out to Deepfactor at support@deepfactor.io to unlock your account.
Disable password authentication