External identity provider setup

DevRev can be configured to use external identity providers for SSO.

If you want DevRev to use an external identity provider, follow the instructions for your organization’s provider.

Before you begin

To register DevRev as a SAML 2.0 application, you need the slug for your dev org.

To get the dev_oid and slug, run the following command:

1 curl --location --request GET 'https://api.devrev.ai/internal/dev-orgs.self.get' \
2 --header 'Authorization: <your PAT>'

In the response, the dev_oid is returned as the display_id.

Ensure the connection_name combines the dev_oid prefix with a custom string and matches the regex pattern:

1 ^`[a-zA-Z0-9]`(-`[a-zA-Z0-9]`|`[a-zA-Z0-9]`)*$

This means it must:

• Start with an alphanumeric character.
• Contain alphanumeric characters or hyphens, without consecutive or trailing hyphens.
• Be unique within your organization.
• Follow the pattern of: <dev_oid>-<CUSTOM-STRING>.

The API call to create the connection fails if this pattern is not followed.

Setup DevRev as service provider on identity provider

You can register DevRev as a service provider in any identity provider that supports SAML 2.0 or OpenID Connect (OIDC). The following are some common examples:

Configure DevRev to use your identity provider

After registering DevRev as an application in your identity provider, you need to create an authentication connection in DevRev that links to your identity provider. This connection enables DevRev to authenticate users through your external identity provider.

Before proceeding, ensure you have the following:

• A Personal Access Token (PAT) with admin permissions.
• Connection details from your identity provider setup.
• Your dev_oid and organization slug from the previous steps.

Step 1: Create the authentication connection

An authentication connection is a configuration object that tells DevRev how to communicate with your identity provider. Use the auth connections create API to create this connection.

Choose the appropriate protocol based on your identity provider:

1 curl --location --request POST 'https://api.devrev.ai/dev-orgs.auth-connections.create' \
2 --header 'Authorization: Bearer <your PAT>' \
3 --header 'Content-Type: application/json' \
4 --data-raw '{
5   "type": "samlp",
6   "sign_in_endpoint": "<sign_in_endpoint>",
7   "signing_cert": "<signing_cert>",
8   "connection_name": "<connection_name>",
9   "display_name": "<display_name>"
10 }'
Show more

1 {
2   "auth_connection": {
3     "id": "con_12345678",
4     "display_name": "<display_name>",
5     "enabled": false,
6     "type": "samlp",
7     "sign_in_endpoint": "<sign_in_endpoint>",
8     "connection_name": "<connection_name>",
9   }
10 }
Show more

Step 2: Enable the authentication connection

After successfully creating the connection, enable it using the connection ID from the previous response:

1 curl --location --request POST 'https://api.devrev.ai/dev-orgs.auth-connections.toggle' \
2 --header 'Authorization: Bearer <your PAT>' \
3 --header 'Content-Type: application/json' \
4 --data-raw '{
5   "id": "<CONNECTION_ID>",
6   "toggle": "enable"
7 }'
Show more

Expected successful response:

1 {}

Step 3: Test and verify the setup

Follow these steps to ensure your SSO integration is working correctly:

1. Check the login page:

   • Go to: https://app.devrev.ai/<DEV_ORG_SLUG>
   • You should see a new SSO login option with your identity provider's name

2. Test user authentication:

   • Use a test user account that's assigned to the DevRev application in your identity provider
   • Click the SSO login option and complete the authentication flow
   • Verify the user is successfully logged into DevRev

3. Test edge cases:

   • Try logging in with a user not assigned to the DevRev application (should fail)
   • Test logout functionality
   • Verify session timeout behavior

• Start with a test user account before rolling out to all users.
• Test both successful and failed authentication scenarios.

Step 4: Manage authentication methods (Optional)

After successfully enabling SSO, you can disable other authentication methods to enforce SSO-only login. This is commonly done to ensure all users authenticate through your organization's identity provider.

Common scenario: If users were previously logging in with Google OAuth and you've now enabled SSO, you can disable Google authentication to force all users to use SSO.

First, get the Google OAuth connection ID:

1 curl --location --request GET 'https://api.devrev.ai/dev-orgs.auth-connections.list' \
2 --header 'Authorization: Bearer <your PAT>'

Look for the Google OAuth connection in the response and note its id field.

Disable Google authentication:

1 curl --location --request POST 'https://api.devrev.ai/dev-orgs.auth-connections.toggle' \
2 --header 'Authorization: Bearer <your PAT>' \
3 --header 'Content-Type: application/json' \
4 --data-raw '{
5   "id": "<GOOGLE_OAUTH_CONNECTION_ID>",
6   "toggle": "disable"
7 }'
Show more

IDP initiated SSO (Optional)

DevRev supports SP-initiated SSO, which means users always start the authentication process from DevRev. IDP initiated SSO means users start the authentication process from your identity provider's portal. The latter is not supported on DevRev.

A workaround for supporting IDP-initiated SSO is to bookmark your DevRev workspace URL (that is https://app.devrev.ai/<DEV_ORG_SLUG>) in your IDP. With only SSO Auth connection enabled, the experience would be as seamless as SP-initiated SSO.

Parameter reference

• <your PAT>: Your Personal Access Token with admin permissions
• <dev_oid>: Your DevRev organization ID (from the initial API call)
• <CUSTOM-STRING>: A custom identifier you choose (must be consistent across all configurations)
• <connection_name>: A unique identifier for your connection (must follow the naming pattern)
• <display_name>: A human-readable name for your connection
• <DEV_ORG_SLUG>: Your DevRev organization slug
• <CONNECTION_ID>: The ID returned from the connection creation API call :::

Troubleshooting

If you encounter issues:

1. Authentication endpoint errors: Verify the sign_in_endpoint (SAML) or issuer (OIDC) is accessible and returns valid responses.
2. Login failures: Check that users are assigned to the application in your identity provider.

For additional support, contact the DevRev customer success team with your connection details and error messages.