These instructions are for Greptile’s Self-Hosted SSO service. If you are using Greptile on the web and want to enable SSO, please contact us at support@greptile.com.
Follow these instructions to enable Enterprise Single Sign-On (SSO) with SAML via BoxyHQ for your Greptile application.

​
Prerequisites

Ensure the following services are operational:
  • web (Greptile web application)
  • jackson (BoxyHQ SSO service)

​
Configure Jackson Service

Set these environment variables for the Jackson service:
VariableDescriptionExample
DB_ENCRYPTION_KEYEncryption keyopenssl rand -base64 32
HOST_URLJackson service URLsso.greptile.com
EXTERNAL_URLExternal Jackson URLhttps://sso.greptile.com
JACKSON_API_KEYSAPI Keys for Jacksonopenssl rand -base64 32
SAML_AUDIENCEAudience identifierhttps://sso.greptile.com
CLIENT_SECRET_VERIFIERSecret verifier (alphanumeric only)dummy
NEXTAUTH_ADMIN_CREDENTIALSAdmin credentialsadmin@greptile.com:mysupersecretpassword
PUBLIC_KEYCertificate (see Jackson docs)Starts with -----BEGIN CERTIFICATE-----
PRIVATE_KEYPrivate key (see Jackson docs)PEM formatted
NEXTAUTH_URLSame as EXTERNAL_URLhttps://sso.greptile.com
NEXTAUTH_SECRETJWT secret from web serviceJWT secret
IDP_ENABLEDEnable IdPtrue

​
Set Up Database Entries

  1. Log in to your PostgreSQL database.
  2. Create or locate an existing Organization.
  3. Generate an InternalApiKey linked to that Organization: 
    openssl rand -base64 36
  4. Create a new SamlConnection:
    • Set org_id to your Organization ID.
    • Set tenant_id to your email domain (e.g., example.com).

​
Configure SSO Connection

  1. Visit the Jackson admin console.
  2. Log in using admin credentials configured earlier.
  3. Navigate to Enterprise SSO → Connections.
  4. Click New Setup Link.
    • Set tenant to user’s email domain.
    • Set product as greptile.
    • Allowed redirect URL: https://<greptile_web_domain>
    • Default redirect URL: https://<greptile_web_domain>/login/saml
  5. Generate the setup link.
  6. Share the setup link with your IdP admin for SSO configuration.

​
Completing SSO Setup

Once configuration is complete:
  • Users can log in to the web app via SSO, by entering their email.
  • New SSO users will automatically be added to the configured Organization.

​
Important Notes

  • AUTH_BOXYHQ_SAML_SECRET in your web service must match Jackson’s CLIENT_SECRET_VERIFIER and should not include special characters.