Single Sign-On (SAML)

​

Prerequisites

1. A Premium license with the SSO feature.
2. A SAML 2.0-compatible identity provider.

​

Setup

1

Enable SSO in your config

Add your license key and enable SSO in convoy.json:

convoy.json

{
  "license_key": "your-license-key",
  "auth": {
    "sso": {
      "enabled": true,

      // [optional] Override the callback URL Convoy gives to your IdP.
      // Defaults to the incoming request origin. Set this if Convoy is
      // behind a reverse proxy or load balancer.
      "redirect_url": "https://convoy.yourcompany.com/saml"
    }
  }
}

Alternatively, use environment variables:

export CONVOY_LICENSE_KEY="your-license-key"
export CONVOY_SSO_ENABLED=true

# Optional — same as redirect_url above
export CONVOY_SSO_REDIRECT_URL="https://convoy.yourcompany.com/saml"

2

Restart Convoy

Restart your instance to apply the new config.

3

Configure your SAML connection

In the Convoy dashboard, go to Organisation Settings and click Configure SSO.

This opens the SSO admin portal where you select your identity provider and complete the SAML setup.

The portal provides the ACS URL and SP Entity ID you’ll need to enter in your IdP. Configure exactly one SAML connection.

If you need multiple SAML connections, reach out to us at [email protected].

4

Login with SSO

On the login page, click Login with SSO. You’ll be redirected to your IdP, and after authentication you’ll land back in Convoy signed in.

​

How It Works

1. You click Login with SSO on the login page.
2. Convoy redirects you to your IdP for authentication.
3. You authenticate with your IdP.
4. The IdP sends a SAML assertion back to Convoy.
5. Convoy validates the assertion and issues a short-lived token.
6. Your browser lands on Convoy’s /saml callback with this token.
7. Convoy exchanges the token for a session and logs you in.

​

Troubleshooting

​

”auth.sso.redirect_url is required for SSO login”

{
  "host": "https://convoy.yourcompany.com"
}

​

SSO button doesn’t appear on the login page

• Check that your license includes the SSO feature.
• Verify auth.sso.enabled is true.
• Restart Convoy after config changes.

​

”Authentication failed” after IdP redirect

• Check that the SAML connection in the SSO portal is configured correctly.
• Ensure the ACS URL and SP Entity ID in your IdP match the values shown in the SSO portal.

​

Blank page or errors after callback

• Make sure you’re running the latest version of Convoy.
• Clear your browser cache and try again.

​

Related

• Licensing — Get and configure a Premium license
• Google SSO — Sign in with Google OAuth
• RBAC — Manage permissions after sign-in