Skip to main content

Configure SSO Authentication

Enterprise Feature

SSO authentication is available in Agenta Enterprise Edition (self-hosted). Set AGENTA_LICENSE=ee to enable enterprise features.

Agenta supports Single Sign-On (SSO) through OpenID Connect (OIDC) providers. When you configure an SSO provider's environment variables, the corresponding login button automatically appears on the sign-in page alongside email and other social login options.

Supported SSO Providers​

ProviderProtocolRequired Variables
OktaOIDCOKTA_OAUTH_CLIENT_ID, OKTA_OAUTH_CLIENT_SECRET, OKTA_DOMAIN
Azure ADOIDCAZURE_AD_OAUTH_CLIENT_ID, AZURE_AD_OAUTH_CLIENT_SECRET, AZURE_AD_DIRECTORY_ID
BoxySAMLSAML (via BoxyHQ)BOXY_SAML_OAUTH_CLIENT_ID, BOXY_SAML_OAUTH_CLIENT_SECRET, BOXY_SAML_URL

Okta​

1. Create an application in Okta​

  1. Sign in to your Okta Admin Console
  2. Navigate to Applications → Applications → Create App Integration
  3. Select OIDC - OpenID Connect as the sign-in method
  4. Select Web Application as the application type
  5. Configure the application:
    • App integration name: Agenta (or your preferred name)
    • Grant type: Authorization Code
    • Sign-in redirect URI: https://<your-agenta-domain>/auth/callback/okta
    • Sign-out redirect URI: https://<your-agenta-domain>
  6. Under Assignments, select who can access the application (e.g., specific groups or everyone)
  7. Click Save
  8. Copy the Client ID and Client Secret from the application settings
  9. Note your Okta domain (e.g., dev-12345.okta.com or your-company.okta.com)

2. Set environment variables​

Add the following to your .env file or docker-compose configuration:

OKTA_OAUTH_CLIENT_ID=your-client-id
OKTA_OAUTH_CLIENT_SECRET=your-client-secret
OKTA_DOMAIN=your-okta-domain.okta.com

3. Restart Agenta​

Restart your Agenta deployment. The "Continue with Okta" button will appear on the login page.

Callback URL

The sign-in redirect URI configured in Okta must exactly match https://<your-agenta-domain>/auth/callback/okta. If you're running locally without SSL, use http:// instead. No trailing slash.

Azure AD​

1. Register an application in Azure​

  1. Sign in to the Azure Portal
  2. Navigate to Azure Active Directory → App registrations → New registration
  3. Configure:
    • Name: Agenta
    • Supported account types: Choose based on your requirements
    • Redirect URI: Select Web and enter https://<your-agenta-domain>/auth/callback/azure-ad
  4. Click Register
  5. Copy the Application (client) ID and Directory (tenant) ID
  6. Navigate to Certificates & secrets → New client secret
  7. Copy the Secret Value

2. Set environment variables​

AZURE_AD_OAUTH_CLIENT_ID=your-application-client-id
AZURE_AD_OAUTH_CLIENT_SECRET=your-client-secret-value
AZURE_AD_DIRECTORY_ID=your-directory-tenant-id

3. Restart Agenta​

Restart your deployment. The "Continue with Azure AD" button will appear on the login page.

BoxyHQ SAML​

BoxyHQ provides a SAML-to-OIDC bridge, allowing Agenta to support any SAML 2.0 identity provider.

1. Set up BoxyHQ SAML Jackson​

Follow the BoxyHQ SAML Jackson documentation to deploy and configure the SAML bridge with your identity provider.

2. Set environment variables​

BOXY_SAML_OAUTH_CLIENT_ID=your-boxy-client-id
BOXY_SAML_OAUTH_CLIENT_SECRET=your-boxy-client-secret
BOXY_SAML_URL=https://your-boxy-instance.com

3. Restart Agenta​

Restart your deployment. The SAML login option will appear on the login page.

How it works​

When you set the environment variables for an SSO provider:

  1. The provider is registered with SuperTokens (the authentication backend) at startup
  2. The frontend detects the configured provider and shows the corresponding login button
  3. When a user clicks the button, they are redirected to the provider's login page
  4. After authentication, the provider redirects back to Agenta's callback URL
  5. Agenta creates or matches the user account and logs them in

All SSO providers configured via environment variables are available globally — every user sees the login buttons on the sign-in page.

Combining SSO with other login methods​

SSO providers work alongside other authentication methods. You can enable any combination of:

  • Email/password or Email OTP (configured via SUPERTOKENS_* vars)
  • Google OAuth (configured via GOOGLE_OAUTH_* vars)
  • GitHub OAuth (configured via GITHUB_OAUTH_* vars)
  • SSO providers (Okta, Azure AD, BoxySAML as described above)

To restrict login to only SSO (disabling email and social login), configure the organization's access controls in Settings → Access & Security after your first admin signs in.