Single sign-on authentication

If you want to make it really easy for your users to log in, or have some compliance requirements around user access/provisioning, you can add one-click login with single sign-on (SSO). We also allow just-in-time provisioning of users, which means that your team members can create their account self-serve (see below), and enforcing log in through an SSO provider to fit all your compliance / IT needs.

Some SSO features may not be available in all plans, 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 and SAML configuration.

Authentication domains need to be verified if you are on PostHog Cloud. If you are on self-hosted, you don't need to worry about domain verification.

To add an Authentication domain, go to your Organization settings (/organization/settings#authentication-domains).

For security purposes and to prevent misuse, 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 so you can 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

Self-serve

Enterprise

When enabled, 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. For self-hosted, this is any provider you configured; for Cloud this is GitHub, GitLab, Google, and SAML if you configured it.

To enable just-in-time user provisioning, navigate to 'Authentication domains' in your Organization settings (accessible via the account settings menu in the top-right) and use the 'Enable automatic provisioning' toggle.

SSO enforcement

Where is this feature available?

Free / Open-source

Self-serve

Enterprise

You may want to force users log in and/or sign up to your organization using a specific SSO provider. When this is enabled, users will not be able to log in using a password, nor request password resets, and will only be able to use the provider you specified. This will apply for administrators and organization owners too. Please be sure your SSO configuration works correctly before enabling this.

Please be aware 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 (see SAML below).

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

Where is this feature available?

Free / Open-source

Self-serve

Enterprise

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.

2. Register your application

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

3. Find your Client ID and Client Secret

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

5. 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

Where is this feature available?

Free / Open-source

Self-serve

Enterprise

1. Go to Settings -> Applications in your GitLab instance (click here for GitLab.com)

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

Where is this feature available?

Open-source

Free

Self-serve

Enterprise

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://app.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.

SAML

Where is this feature available?

Free / Open-source

Self-serve

Enterprise

SAML (Security Assertion Markup Language) enables users to have a single set of credentials to access multiple systems. It also has the benefits of centralizing user management to aid maintenance. If your company has an Identity Provider (IdP) that uses SAML, you can integrate it with PostHog (Service Provider, SP) so your users can authenticate through your SAML portal instead of having an additional password for PostHog.

PostHog supports multi-tenant SAML, which means you can have multiple SAML authentication servers within a single instance and even a single organization. The limitation is that you can only have one SAML provider per domain. So for instance, users with email address at example.com can log in with SAML provider A and users with email address at anotherdomain.net can use SAML provider B.

Please be sure to update PostHog to version 1.35.0 onwards. Before this version, SAML used to work instance-based with environment variables and this behavior is fully deprecated.

Warnings

When using SAML to authenticate your users in PostHog there are a few considerations to keep in mind. Please make sure to read them to avoid any security issues.

1. Only use SAML with identity providers that validate the user's email address or in a context where you control a user's email address. When first logging in, we use the email address that the IdP passes to associate with a user. If a user can spoof their email address with your IdP, they'll be able to impersonate your users.
2. Enabling or enforcing SAML login will not disable Personal API Key usage. This means that even users can always create a Personal API Key and use it instead of SAML authentication (API-only, not for the app).
3. Our SAML integration only handles authentication and automatic user provisioning. If you remove a user from your IdP, their account will not be removed or disabled from PostHog, they might just be unable to log in (depending on your configuration).
4. When you enable or enforce SAML, any existing user passwords are preserved. This means if you ever want to go back (or something breaks down with your authentication), you can just stop enforcing SAML and you'll be able to log in with your existing credentials.

Setting up SAML

For SAML to work your IdP and PostHog (SP) need to exchange information. To do this, you need to configure some settings in your IdP and on PostHog. Depending on your IdP you might need to pass PostHog information first, or the other way around. See details below.

1. If you are on self-hosted, make sure you have properly set up your SITE_URL environment variable configuration.
2. If you are on self-hosted, you will need to be running your PostHog instance over TLS.
3. Register a new SAML 2.0 application with your IdP. If you need to pass PostHog's information to your provider first, set the following values below (alternatively if your IdP supports it, you can obtain our XML metadata from <yourdomain>/api/saml/metadata/)
   • Single Sign On URL (also called ACS Consumer URL): <yourdomain>/complete/saml/ or https://app.posthog.com/complete/saml/ for PostHog Cloud.
   • Audience or Entity ID: Your Site URL value (verbatim)
   • RelayState: empty or default (will be set on every request)
4. For SAML to work properly with PostHog, we need to receive at least the following information from your IdP in the SAML assertion payload: ID, email and first name. Optionally, you can also pass the last name. By default, PostHog expects these attributes with a certain name.

3. You will now need to obtain some parameters from your IdP and configure them in PostHog for the appropriate domain in Authentication domains. Depending on your provider, they may only provide this information as an XML metadata file. If this is the case, you can open the file in a text editor and obtain the required values from there.

   • SAML Entity ID: Will be identified as EntityID or IdP issuer. This can vary greatly between providers, but it usually looks like a URL.
   • SAML ACS URL: The endpoint to which the SAML requests are posted. It's usually called SAML endpoint or IdP sign-on URL.
   • SAML X.509 certificate: The public certificate used to validate SAML assertions from your IdP. It must be in X509 (almost all providers will provide it in this format). If your provider gives you the certificate as a file (usually .pem), just open it with a text editor to get the contents. When setting this certificate be sure to keep any spaces and new lines (don't format it). The first and last line of the certificate (e.g. -----BEGIN CERTIFICATE-----) are optional.

   

4. Once you've configured all the settings above, you can now log out and attempt logging in using SAML (you just need to enter your email address).

5. For security reasons, we don't output errors directly in your browser when something goes wrong. If you need help debugging on PostHog cloud, please contact support. To debug your self-hosted configuration, you have two options:

   • Recommended. Check your app logs (this varies depending on your deployment). Any errors will be logged there.
   • If everything else fails, temporarily set environment variable DEBUG=1, errors will be fully displayed now in the browser. Please be sure to remove this once you're done, ugly things can happen if you don't.

Example: OneLogin

OneLogin quick setup

You can quickly connect OneLogin and PostHog by using the prebuilt integration.

1. In OneLogin admin, go to Applications and click on "Add App". Search for "PostHog" and create your app.
2. Go to the "Configuration" tab and where it says "PostHog domain name" enter your PostHog's instance domain (as it's also specified in the SITE_URL environment variable), but don't include any protocol or trailing slashes. Examples: playground.posthog.com, myposthog.mydomain.com, myposthogdomain.com.
3. Go to the "SSO" tab. This is where you'll obtain the information you need to pass to PostHog.
   • "Issuer URL" needs to be set as SAML Entity ID.
   • "SAML 2.0 Endpoint (HTTP)" needs to be set as SAML ACS URL.
   • On "X.509 Certificate" click on "View Details". Copy the full certificate and set it as SAML X.509 certificate.
4. You're good to go! Click on the "Login with SSO" in PostHog's login page.

OneLogin advanced

Use this option if you want to add additional configurations to your app that are not supported with the default app catalog.

1. In OneLogin admin, go to Applications and click on "Add App".
2. Search for "SAML" and select "SAML Custom Connector (Advanced)". Set name to "PostHog".
3. Go to the "Configuration" tab and edit the following attributes (leave everything else as default)
   • Audience (EntityID): Set to the exact same value as your SITE_URL environment variable.
   • ACS (Consumer) URL Validator: Set to a regex that only matches <yourdomain>/complete/saml/. For instance: ^https:\/\/app.posthog.com\/complete\/saml\/$
   • ACS (Consumer) URL: Set to <yourdomain>/complete/saml/.
4. Go to the "Parameters" tab. You will add the following parameters. Be sure to check "Include in SAML assertion".
   • email to match the user's email ("Email")
   • first_name to match the user's first name ("First Name")
   • last_name to match the user's last name ("Last Name")
5. Go to the "SSO" tab. This is where you'll obtain the information you need to pass to PostHog.
   • "Issuer URL" needs to be set as SAML Entity ID.
   • "SAML 2.0 Endpoint (HTTP)" needs to be set as SAML ACS URL.
   • On "X.509 Certificate" click on "View Details". Copy the full certificate, removing the first and last lines and set it as SAML X.509 certificate.
6. You're good to go! Click on "Login with SSO" in the login page.

Example: Okta

We're working with the Okta team to add PostHog to their Integration Catalog and simplify your set up experience. In the meantime, you'll find some pointers on how to connect Okta to PostHog below.

1. In Okta admin, go to Applications and click on "Create App Integration".
2. Select the "SAML 2.0" option. In the next step, set "PostHog" as the name.
3. Fill in the following attributes in the SAML settings. Do not click next yet.
   • In "Single sign on URL" enter <yourdomain>/complete/saml/.
   • In "Audience URI (SP Entity ID)" enter the exact same value as your SITE_URL environment variable.
4. In the "Attribute Statements" section, you'll add the following attributes.
   • email with value user.email
   • first_name with value user.firstName
   • last_name with value user.lastName
5. In the final step just select option "I'm an Okta customer adding an internal app".
6. Navigate now to the "Sign On" tab of the application and click on "View Setup Instructions". This is where you'll obtain the information you need to pass to PostHog.
   • "Identity Provider Single Sign-on URL" needs to be set as SAML ACS URL.
   • "Identity Provider Issuer" needs to be set as SAML Entity ID.
   • "X.509 Certificate" needs to be set as SAML X.509 certificate.
7. You're good to go! Click on "Login with SSO" in the login page.