SSO

Contents

Single sign-on

SSO makes logging in easier for users to log and compliance easier for administrators.

We also allow support just-in-time provisioning of users with our platform packages, which means that team members can self-serve creating their account, while still enforcing log in through a specified SSO provider.

Some SSO features are included in our platform packages. Please review each section below for details.

Authentication domains

SSO configuration mostly occurs in your Organization settings and is based on authentication domains. You need to have a verified authentication domain in order to set Just-in-time provisioning, SSO enforcement, SAML configuration, and SCIM provisioning.

Authentication domains need to be verified if you are on PostHog Cloud.

To add an Authentication domain, go to your Organization settings.

Authentication domains must be verified in PostHog Cloud. We do this through DNS verification. You will have to add a TXT record to your DNS zone with a specific value to prove you have authority over the domain. Verification only needs to be done once, but the record must be kept at all times, as we do periodic DNS verification.

Adding a TXT record depends on your DNS provider (e.g. Cloudflare, Google Domains, ...) and your provider should provide simple instructions on how to add the required record. The record should look as follows:

  1. Select TXT for the record type.

  2. The Name/Host/Alias field should be _posthog-challenge.yourdomain.com. where yourdomain.com is your actual domain name. Some DNS providers may require the dot in the end or not, and some providers may auto-populate your domain name.

  3. The value of the record is provided in the domain verification screen (e.g. lRk16Vtg7PJdcltYlCPq07vd7vwu7t)

  4. The time-to-live (TTL) should be the default or 3600.

Just-in-time user provisioning

Where is this feature available?
Free / Open-source
Paid
Boost
Scale
Enterprise

Just-in-time user provisioning creates a new account whenever a first-time user logs in using any available SSO provider and an email address that matches your verified domain. PostHog Cloud supports GitHub, GitLab, Google, and SAML if you have configured it.

To enable just-in-time user provisioning, navigate to Authentication domains in your Organization settings and use the Enable automatic provisioning toggle.

SSO enforcement

Where is this feature available?
Free / Open-source
Paid
Boost
Scale
Enterprise

You may want to force users log in and/or sign up to your organization using a specific SSO provider.

When SSO enforcement is enabled, users cannot:

  1. Log in using a password
  2. Request password resets
  3. Use any SSO provider other than the one specified

This applies to administrators and organization owners, too. Please be sure your SSO configuration works correctly before enabling this.

If you enable SSO enforcement for a particular domain, any user who signs up or logs in with an email address on that domain will be required to use the SSO provider you enforced. This applies to existing users too and users not in your organization.

You can enable SSO enforcement through Authentication domains in your Organization settings.

Third-party providers

PostHog currently supports GitHub, GitLab and Google as SSO providers. All providers are available and readily configured on PostHog Cloud.

This section contains instructions on how to configure each provider in your self-hosted instance. All the providers in this section (i.e. everything except SAML) is configured instance-based. SAML is configured domain-based.

Looking for a provider that's not here? Reach out to us, we might be able to help.

Please note that you will not be able to use SSO with the first user of your instance. You will have to create a user with a regular password and you will later be able to log in with SSO (even for that first user).

GitHub

  1. Go to Register a new OAuth application

If you want to have this application as part of an organisation, you'll need to go to your organization's settings -> OAuth apps -> New OAuth App.

  1. Register your application

    • Homepage URL needs to be the url of your PostHog instance
    • Authorization callback URL needs to be the url of your PostHog instance + /complete/github/

  2. Find your Client ID and Client Secret

  3. Add those two settings as SOCIAL_AUTH_GITHUB_KEY and SOCIAL_AUTH_GITHUB_SECRET and restart your server.

  4. When logging in, or signing up to a team you can now log in using PostHog!

We don't support logging in with GitHub when setting up PostHog for the very first time.

GitLab

  1. Go to Settings -> Applications in your GitLab instance (open the GitLab.com applications settings)

  2. Register your application

    • Redirect URI needs to be the url of your PostHog instance + /complete/gitlab/
    • Tick read_user as scope.

  3. Find your Application ID and Secret

  4. Add those two settings as SOCIAL_AUTH_GITLAB_KEY and SOCIAL_AUTH_GITLAB_SECRET. If you're hosting GitLab yourself you'll also need to add SOCIAL_AUTH_GITLAB_API_URL, which is the full URL to your GitLab instance.

Google

❗️ Google SSO is not available for open source deployments.

To set up Google SSO please follow these instructions:

  1. Go to the Google Developer Console at https://console.cloud.google.com/apis/dashboard. Be sure to select the proper Google account and the right project for your app (or create one if you don't have it).

  2. Navigate to the Credentials section.

  3. Click on Create credentials and select OAuth client ID to generate your credentials.

    • On Application Type select Web application and enter a meaningful name (e.g. PostHog Self-hosted).
    • On the Authorized JavaScript origins section add the root domain (with protocol) for your PostHog instance (e.g. https://us.posthog.com)
    • On the Authorized redirect URIs section add the following URI (replace with your hostname): https://{hostname}/complete/google-oauth2/.
    • Click on Save.

  4. You will now get a Client ID and Client secret. Set those as environment variables SOCIAL_AUTH_GOOGLE_OAUTH2_KEY and SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET respectively.

  5. Additional. If this is your first time setting SSO for this project, you may need to set up some additional configuration for your OAuth Consent Screen. We highly recommend you only enable internal access (if it makes sense for you), as it'll make things more secure and the verification process faster. Check out Google's official docs to learn more.

Still have questions?

Was this page useful?