Skip to content
  • Auth and access
  • Enterprise connections

Custom SAML enterprise connection

In Kinde, you can use SAML as your authentication protocol. Kinde acts as a service provider (SP), so you still need to bring your own identity provider (IdP) to set it up. Identity providers can include Google, Microsoft, Cloudflare, and others.

Looking to let your own team sign in to third-party tools using Kinde as the identity provider? See Workforce identity in Kinde.

Note: Since there are differences between set ups for each IdP, we are unable to provide full details on how to configure them all to connect with Kinde. However, the fields we mention below, should have similar names in your IdP. Some concepts are explained in the advanced SAML configurations topic.

User provisioning

Link to this section

Before you set up SAML, you can import users in bulk, add them via API, or manually in Kinde. Alternatively, you can also take advantage of just-in-time (JIT) provisioning (Step 13 below) when you set up the connection.

(Optional) Signed certificate and private key

Link to this section

You can increase SAML security by adding a certificate and private key pair to your setup. Your IdP will check that the certificate and private key matches, each time a user authenticates this way.

You can obtain the certificate and key from your IdP or you can generate yourself, see below.

Generate a certificate and private key pair

Link to this section
  1. In your preferred system, run a command to generate a certificate and key. For example, on *nix systems, the command is:

    Generate a certificate and private key pair
    openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout private_key.key -out certificate.crt
  2. This command may also work in other systems, such as WSL on Windows. Alternatively, you can try installing openssl binaries for your system.

  3. Once the files are generated, save them locally.

  4. Add the certificate to your IdP settings. The certificate there and the one in Kinde must match exactly. Instructions for how to do this varies, depending on your IdP.

  5. Copy the certificate and private key details into Kinde as per the procedure below.

Advanced configurations

Link to this section

Depending on your SAML set up, you may need to include advanced configurations for your connection. See Advanced SAML configurations

Step 1: Add SAML connection in Kinde

Link to this section

Add a connection for a specific organization

Link to this section
  1. Go to Organizations and open the organization.
  2. In the menu, select Authentication, then select Add connection.
  3. In the Add connection window, select New enterprise connection, then click Next.
  4. Select the connection type you want and then select Next.
  5. Next: ‘Step 2: Configure the connection’.

Add a connection that can be shared across multiple organizations

Link to this section
  1. Go to Settings > Environment > Authentication.
  2. Scroll to the Enterprise connection section and select Add connection. The Add connection window opens.
  3. Select the connection type you want and then select Next.
  4. Next: ‘Step 2: Configure the connection’.

Step 2: Configure the connection

Link to this section
  1. Enter a name for the connection. It must match the name in your SAML setup.

  2. Enter an Entity ID. In SAML metadata this identifier is often labeled entityID. For SAML SSO, the entity ID must match between your Kinde enterprise connection and your IdP. This is a value you can make up using a random alphanumeric string, e.g. 5836g209gbhw09r8y0913. The Entity ID you enter here must be configured exactly the same in your identity provider (unless your IdP is Microsoft Azure).

    configuration custom saml screen

  3. If Microsoft is your provider and your app is a bit older, you may need to add spn: to the beginning of the Entity ID string in Kinde, e.g. spn:5836g209gbhw09r8y0913. This is not required for newly created apps.

  4. Provide the identity provider’s metadata. Kinde uses it to find your IdP’s sign-in endpoint and the certificates it signs responses with. There are two ways to do this; use one or the other.

    idp metadata url and xml

    • IdP metadata URL: Enter the metadata URL your identity provider gives you. Kinde reads the file from this URL at every sign-in, so any certificate your IdP adds to it is trusted automatically. Leave this blank if you paste the XML below.
    • IdP metadata XML: If your identity provider only gives you the metadata as a file (Google Workspace, for example), paste the file contents here instead. Kinde stores this copy and uses it until you replace it, so you must re-paste the file whenever your IdP rotates its signing certificates.

    If you fill in both fields, Kinde uses the pasted XML and ignores the URL.

  5. Enter a sign in URL if your IdP requires a specific URL.

    optional fields for saml

  6. If you want, select the Sign request algorithm and Protocol binding. The options you choose will depend on what your identity provider prefers or requires.

  7. Select a Name ID format. This helps identify and link user identities between your IdP and Kinde.

  8. Enter an Email key attribute. This is the attribute in the SAML token that contains the user’s email. Setting this value ensures that the email address returned in the SAML response is correctly retrieved. We do not recommend leaving this field blank, but if you do we will set ‘email’ as the attribute.

  9. (Optional) Add a first name and last name key attribute.

  10. Enter any relevant Home realm domains. This is how SAML recognizes a user’s credentials and routes them to the correct sign in page. Note that home realm domains need to be unique across all connections in an environment. Read more about home realm domains.

    Home realm domains in SAML configuration

  11. If you use home realm domains, the sign in button is hidden on the auth screen by default. To show the SSO button, select the Always show sign-in button option.

  12. Copy the relevant reply URL:

    ACS URL and custom domain option

    1. If you don’t use a custom domain, copy the ACS URL.
    2. If you do use a custom domain, select the Use custom domain instead option and copy the custom domain URL. Later, add this URL to your identity provider configuration.
  13. If you want to enable just-in-time (JIT) provisioning for users, select the Create a user record in Kinde option. This saves time adding users manually or via API later.

  14. For an environment-level connection, under Email address trust, select Verify, then trust. For details about the options, see Trusting emails from providers. Organization-level connections show Auto-add users instead.

  15. (Optional) In the Sign SAML request section, paste in the Signed certificate and Private key. You may have got these from your IdP or you may have generated yourself (see procedure above).

  16. Enter any upstream params that you want to pass to the identity provider. Not all providers support this, so check their documentation first.

  17. Switch on the connection. This will make it instantly available to users if this is your production environment.

    1. For environment-level connections, scroll down and select the apps that will use the auth method.
    2. For organization-level connections, scroll down and select if you want to switch this on for the org.
  18. Select Save.

Next: Complete any additional configuration in your identity provider’s settings, such as adding the Entity ID and return URL.

Step 3: Test the connection

Link to this section

Once you have entered the ACS URL in your identity provider, the connection should be enabled.

  1. Go to your test application and attempt to sign in.
  2. If you left the Home realm domains field blank in Kinde, when you launch your application, you should see a button to sign in. Click it and go to step 4.
  3. If you completed the Home realm domains field, you should be redirected immediately to your IdP sign in screen.
  4. Enter your IdP details and complete any additional authentication required.

Keep IdP signing certificates current

Link to this section

Your identity provider signs every SAML response with a certificate, and Kinde checks that signature against the certificates published in the IdP metadata. Signing certificates expire, so at some point your IdP will rotate to a new one. This section explains how Kinde handles that, and what you need to do.

How Kinde trusts IdP certificates

Link to this section
  • Kinde trusts every signing certificate in the IdP metadata, not just one. If the metadata lists an old and a new certificate, both are trusted.
  • When a response arrives, Kinde finds the certificate that signed it among those in the metadata, and checks that this certificate is within its validity dates. The other certificates in the metadata are not checked, so an expired certificate can remain listed without breaking sign-in, as long as your IdP is signing with a valid one.
  • Kinde does not enforce the validUntil attribute on the metadata file itself. Some providers, including Google, set it to the expiry date of the current certificate.

This means you can publish the new certificate alongside the old one, switch your IdP over whenever you are ready, and switch back if anything goes wrong. For a connection that uses an IdP metadata URL, you can do this without touching the connection in Kinde. For a connection that uses pasted metadata XML, save the updated metadata in Kinde before you switch.

What to do when your IdP rotates its certificate

Link to this section

The steps depend on how the connection receives the metadata.

Connection uses an IdP metadata URL

  1. Make sure the file at that URL lists the new certificate. If your IdP hosts the file, this is automatic. If you host a copy yourself, download the updated metadata from your IdP and re-upload it.
  2. In your IdP, switch the SAML application to sign with the new certificate.
  3. Test a sign-in. No change is needed in Kinde: the next sign-in reads the updated file.

Connection uses pasted IdP metadata XML

  1. Download the updated metadata from your IdP. It should list both the old and the new certificate.
  2. In Kinde, open the connection, paste the updated file into IdP metadata XML, and select Save.
  3. In your IdP, switch the SAML application to sign with the new certificate.
  4. Test a sign-in.

Do the Kinde step first in either case. Once the new certificate is in the metadata Kinde reads, the switch in your IdP cannot interrupt sign-in.

Rolling back

If sign-in fails after the switch, change your IdP back to the previous certificate. It keeps working until its expiry date, as long as it is still listed in the metadata. You can remove the old certificate from the metadata after it expires, but leaving it there does no harm.

Expiry warnings in Kinde

Link to this section

For connections that use pasted metadata XML, Kinde checks the certificates in the stored file. When the newest signing certificate expires within 30 days, or has already expired, you will see an SSO connection issue banner on the Kinde home page and on the connection’s configuration dialog, naming the connection and the expiry date. Paste the updated metadata from your IdP to clear it.

Connections that use a metadata URL are not checked, because Kinde reads the IdP’s current certificates at every sign-in.