Skip to main content
This guide connects your self-hosted instance to an identity provider over SAML 2.0, so people sign in with their company account instead of a Compiler password. It works with any SAML identity provider, such as Okta, Microsoft Entra ID, Google Workspace, OneLogin or JumpCloud. You set it up in Settings > Security > SAML. Nothing goes in environment variables, and nothing needs a restart.

Prerequisites

  • You’re an owner or admin of your instance’s first organization. Single sign-on applies to everyone on the instance, so only that organization’s admins can manage it.
  • You can create a SAML app in your identity provider, or someone who can is helping you.
  • PUBLIC_URL is set to the address people use to reach your instance, such as https://compiler.yourdomain.com. Compiler builds the addresses your identity provider needs from it. Your identity provider doesn’t need to reach your instance, because the browser carries every sign-in to it.

How it works

  • People click Continue with SAML SSO on the login page, or open Compiler from their identity provider’s dashboard. Both work.
  • Compiler identifies people by email address, so the identity provider must send it. See Step 1.
  • The first time someone signs in, Compiler creates their account and adds them to the organization as a member. If they were invited with a different role, they get that role instead.
  • Compiler accepts a SAML response only once and only for a few minutes, and the assertion must be signed.

Step 1: Create the SAML app in your identity provider

In your identity provider’s admin console, create a new SAML 2.0 app, sometimes called a custom or non-gallery app. Fill it in from Settings > Security > SAML in Compiler, where each value has a Copy button. If your identity provider can import service provider metadata, click Download next to Metadata and upload the file instead. Leave the relay state blank. If the Name ID can’t be the email address, send the email address as an attribute named email instead.

Step 2: Assign people

In your identity provider, assign the people or groups who should use Compiler to the app. People who aren’t assigned can’t sign in through it.

Step 3: Give Compiler the identity provider’s details

Your identity provider shows three values once the app is created, often on a page called setup instructions or SAML metadata. Copy them into Settings > Security > SAML in Compiler and click Save:

Step 4: Turn on single sign-on

  1. Go back to Settings > Security.
  2. Under Authentication methods, turn on Single sign-on.
  3. In a private browser window, open Compiler and click Continue with SAML SSO. Your identity provider signs you in and sends you back to Compiler.

Turn off password sign-in

Once single sign-on works, you can make everyone use it. In Settings > Security, turn off Password sign-in. The login page then shows only Continue with SAML SSO, and Compiler refuses passwords for every account on the instance.
Make sure your own account can sign in through your identity provider first. With password sign-in off, an admin who isn’t assigned to the SAML app can’t sign in.
To turn password sign-in back on, an admin signs in through single sign-on and turns it on again. One of the two methods always stays on.

Remove someone’s access

Removing someone from the SAML app in your identity provider stops them signing in again, but doesn’t remove them from Compiler. A session they already have keeps working until it expires. To remove someone straight away, also remove them in Settings > Members.

Rotate the certificate

When your identity provider’s signing certificate changes, paste the new certificate into Settings > Security > SAML and click Save. Compiler trusts one certificate at a time, so sign-ins fail between the identity provider switching certificates and you saving the new one. Do both within a few minutes of each other.

Troubleshooting

If your identity provider shows an error before sending you back to Compiler, check that the person is assigned to the app and that its assertion consumer service URL matches Compiler’s ACS URL, including https.