SSO, SAML, and SCIM

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 add-ons. 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

Where is this feature available?

Free / Open-source

Paid

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
   • Authorization 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

Paid

Enterprise

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

Where is this feature available?

Open-source

Free

Paid

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

SAML

Where is this feature available?

Free / Open-source

Paid

Boost

Scale

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.

If you are self-hosting, please be sure to update PostHog to version 1.35.0+. 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. We provide complete examples for OneLogin and Okta below, but the general flow is:

1. If you are on self-hosted, make sure you have properly set up your SITE_URL [environment variable][env-vars] 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://us.posthog.com/complete/saml/ for PostHog Cloud US or https://eu.posthog.com/complete/saml/ for PostHog Cloud EU.
   • Audience or Entity ID: Your Site URL value (verbatim), on PostHog Cloud this is https://us.posthog.com or https://eu.posthog.com
   • RelayState: On PostHog cloud, get your RelayState value from the SAML configuration modal in your PostHog Organization settings. For self hosted, 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.
     • If using Azure AD the setting to use for this field is called Azure AD Identifier.
   • 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 and provide the error ID that is shown at the bottom of the error page. 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 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][env-vars]), 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 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 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)

   • In the Audience (EntityID) enter https://us.posthog.com.
     • If you are using our EU deployment, use https://eu.posthog.com.
     • If you are self-hosting, enter the exact same value as your SITE_URL [environment variable][env-vars].
   • Set the ACS (Consumer) URL Validator to a regex that only matches <yourdomain>/complete/saml/. For instance: ^https:\/\/us.posthog.com\/complete\/saml\/$ (or use eu for an EU instance)
   • Set the ACS (Consumer) URL to https://us.posthog.com/complete/saml/.
     • If you are using our EU deployment, use https://eu.posthog.com/complete/saml/.
     • If you are self-hosting, use <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 Login with SSO in the login page.

Example: Okta

1. In Okta admin, go to Applications and click 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 https://us.posthog.com/complete/saml/.
     • If you are using our EU deployment, use https://eu.posthog.com/complete/saml/.
     • If you are self-hosting, use <yourdomain>/complete/saml/.
   • In Audience URI (SP Entity ID) enter https://us.posthog.com.
     • If you are using our EU deployment, use https://eu.posthog.com.
     • If you are self-hosting, enter the exact same value as your SITE_URL environment variable.

4. In the Default Relay State field, enter the RelayState value you obtain from your PostHog Organization Settings page in the SAML configuration modal.

5. In the Attribute Statements section, add the following attributes:

   • email with value user.email
   • first_name with value user.firstName
   • last_name with value user.lastName
   • Permanent ID is not required as Okta sends this automatically.

6. In the final step select the option "I'm an Okta customer adding an internal app".

7. Navigate now to the Sign On tab of the application and click 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 (use the complete URL).
   • X.509 Certificate needs to be set as SAML X.509 certificate.

8. You're good to go! Click Login with SSO in the login page.

SCIM

Where is this feature available?

Free / Open-source

Paid

Boost

Scale

Enterprise

SCIM enables you to automatically sync users and their roles from your identity provider (IdP) into PostHog. This is useful for automatically creating accounts and assigning roles when someone joins your organization, and disabling accounts when they leave.

SCIM is currently in beta and available on request for customers on the Enterprise plan. Contact us to enable it for your organization.

How SCIM works

• Assigning a user to the SCIM app in your IdP creates them in PostHog with the mapped role.
• Removing a user from the app deactivates their PostHog account.
• Users with matching emails in PostHog are updated to match the IdP details and roles.
• Roles are matched by name (case-sensitive).

Prerequisites

Before setting up SCIM, you need:

1. Verified authentication domain in PostHog Cloud
2. SAML SSO configured and working for your domain
3. Identity Provider that supports SCIM 2.0 (e.g., Okta, Entra ID, OneLogin)

Setting up SCIM

1. In PostHog, navigate to Organization settings and go to Authentication domains.

2. Click the (⋯) next to your domain and select Configure SCIM.

3. Copy the SCIM Base URL and SCIM Token. You'll need these for your IdP configuration.

4. In your Identity Provider, configure SCIM for your PostHog application:

   If you already have a SAML app configured and it supports SCIM 2.0 provisioning, you can use that same app. If not, you'll need to create a new app that supports both SAML and SCIM. After setting up SCIM in the new app, migrate your existing SAML configuration and users to it.

   • Set the SCIM Base URL from PostHog
   • Set the Bearer Token (SCIM Token) from PostHog
   • Enable user provisioning

5. Configure role mapping in your IdP. Map your IdP roles to PostHog roles.

6. Assign users and roles to the PostHog application in your IdP, verify that they appear in PostHog.

Example: Okta

If your existing SAML app supports SCIM 2.0 provisioning, you can use it. Otherwise, follow these steps to create a new app that supports both SAML and SCIM:

1. In Okta admin, go to Applications and click Create App Integration.

2. Search for SCIM 2.0 Test App (Auth Bearer Token) and select it.

3. Leave SAML sign-on method enabled. Configure SAML following the steps in the Okta SAML example.

4. In PostHog, open your existing SAML configuration for the domain and update it with the new values from Okta (SAML ACS URL, SAML Entity ID, and SAML X.509 certificate).

5. Navigate to the Provisioning tab in Okta and click Configure API Integration.

6. Check Enable API integration and enter:

   • SCIM Base URL from PostHog
   • API Token (the SCIM Token from PostHog)

7. Click Test API Credentials to verify the connection.

8. In the Provisioning to App settings, enable:

   • Create Users
   • Update User Attributes
   • Deactivate Users

9. Go to the Assignments tab and configure role mapping.

10. Assign users to the PostHog application. Their email, name, and groups will be automatically updated in PostHog.

11. Once everything is working, you can remove or deactivate your old SAML-only application.

Example: OneLogin

If you already have a SAML app configured, you'll need to migrate to an app that supports SCIM provisioning.

1. In OneLogin admin, go to Applications and click Add App.

2. Search for SCIM Provisioner with SAML (SCIM v2 Enterprise, full SAML) and select it.

3. In the Configuration tab, copy the settings from your existing SAML app: SAML Audience URL, RelayState, ACS (Consumer) URL.

4. Go to the Parameters tab and ensure the following attributes are created (they are required for SAML to work correctly):

   • email (Email)
   • first_name (First Name)
   • last_name (Last Name)

5. Navigate to the Configuration tab and paste the SCIM Base URL and SCIM Bearer Token from PostHog into the API Connection section. Click Enable.

6. Go to the Provisioning tab and check Enable provisioning. Select whether you want admin approval for creating or deleting users.

7. To sync roles, go to the Rules tab and create a rule to map OneLogin roles to PostHog roles. To sync all roles as-is:

   • In Actions, select Set Groups in SCIM v2 Provisioner with SAML
   • Select Map from OneLogin
   • For each role with value that matches .*

8. Go to the SSO tab and copy the new Issuer URL, SAML 2.0 Endpoint, and X.509 Certificate. Update your existing SAML configuration in PostHog with these new values.

9. Assign users to the new application. Go to Users, select a user, assign roles, and add them to the application.