Add and configure a SAML application

Add a SAML application to let your team sign in to a third-party tool using Kinde as the identity provider. For background, see Workforce identity in Kinde.

Workforce identity is available on the Kinde Scale plan. Separate plans for workforce identity are coming soon.

Connecting an application involves an exchange of details in both directions. You tell Kinde where to send assertions, and you tell the third-party tool to trust Kinde.

Quickstart

Link to this section

1. Create an application

Link to this section

1. Sign in to your Kinde dashboard, go to Settings > Environment > Applications, and select the Workforce identity tab.

2. Select Add application.

   

3. Choose your application from the catalog. If your tool is not listed, choose SAML application.

4. Kinde creates the application and opens its Details page.

   

2. Configure app details

Link to this section

1. Set a Display name to override the catalog name in your application list. This is useful when you connect more than one instance of the same tool.

2. Select Import SP metadata if your tool publishes a metadata file. Supply the metadata URL or XML. Kinde fills in the entity ID, ACS URL, and certificates for you, saving you time. Select Save to apply the settings.

   

3. In Service provider (SP) configuration, enter the SP entity ID. This is the entity ID configured in the third-party application.

4. Enter the Assertion Consumer Service (ACS) URL. This is where Kinde posts the SAML response.

5. Check the Name ID format. Kinde defaults to the email address format, which suits most applications.

6. Choose the Name ID source, which is the Kinde user field sent as the SAML NameID. Choose Email or User ID. Email is the default.

7. Select Save.

3. Get Kinde IdP metadata

Link to this section

1. Go to the Kinde IdP metadata tab and copy the IdP metadata URL. If your tool supports auto-configuration, use this URL to import all of Kinde’s details at once.

   

2. For manual configuration, copy the following values into the third-party tool’s SAML settings:

   • IdP entity ID: Kinde’s unique identifier for this connection
   • Single sign-on URL: Where the tool sends its authentication requests
   • Single logout URL: Where the tool sends logout requests, if you have configured logout
   • Signing certificate: Used by the tool to verify assertions signed by Kinde

Kinde generates the signing certificate for an application the first time it is actually used. If the certificate field is empty, select Test SSO on this tab, or complete a real sign-in through the application, and the certificate will be created.

4. Map user attributes

Link to this section

Most applications need more than a NameID. On the Attribute mapping tab, map Kinde fields to the SP attribute names your tool expects.

1. Go to the Attribute mapping page.

   

2. Select a Kinde field. You can map standard profile fields and any user properties you have defined.

3. Enter the SP attribute name exactly as the service provider expects it.

4. Select Add mapping to add more.

5. Select Save.

Check the service provider’s SAML documentation for the attribute names it requires. Names are usually case-sensitive and must match exactly.

User property values are the same across organizations. Organization-specific role claims are not supported yet.

5. Choose authentication methods

Link to this section

1. Go to the Authentication tab.
2. Choose which of your authentication connections can be used to sign in to this application. This lets you require a stronger method for sensitive tools than you allow elsewhere.

See Authentication methods for more information.

6. Test the connection

Link to this section

The Test SSO button appears once both the SP entity ID and the ACS URL are set.

1. Go to the Kinde IdP metadata tab.

2. Scroll to the end of the page. Under Test this connection, select Test SSO.

   

Kinde signs you in and runs a real SAML sign-in to the application, so you can confirm the connection before rolling it out.

7. Display the app tile on the self-serve portal

Link to this section

Once the connection works, decide who sees it.

1. Go to the Details tab of your workforce identity application and make sure it is Enabled in the Settings section.

2. Turn on Show on self-serve portal.

   

3. Optionally use Limit to organizations to restrict the tile to chosen organizations. Leave every box unchecked to show the tile to all organizations. This controls the portal tile only, it does not block sign-in from the tool itself.

4. Select Save.

5. Go to Settings > Environment > Self-serve portal.

6. Under User self-management, turn on the Applications toggle.

   

7. Select Save.

The tile appears in the self-serve portal when the user signs in.

Learn more about Self-serve portal for users.

Self-serve portal is not mandatory

Users can sign in by going to the third-party tool directly, which does not depend on the portal setting.

Secure the connection

Link to this section

Restrict access by role

Link to this section

By default, anyone who can sign in to Kinde can sign in to an enabled application. To limit access to people who hold specific roles:

1. Go to the Access control tab.

2. Switch on Enable role-based access control.

3. Select the Allowed roles. Only organization members holding one of these roles can sign in.

   

4. Select Save.

You need at least one role defined for your business before you can turn this on.

Role-based access control is evaluated within an organization. If Kinde cannot determine which organization someone is signing in from, access is denied. Test the sign-in path you expect people to use after turning this on.

Control how often people must sign in

Link to this section

Two separate timers on the Sessions tab decide how long a sign-in stays valid.

• Session lifetime is how much time can pass since the person last authenticated before this application requires a fresh sign-in, even if their browser session is still active. The default is 86400 seconds (24 hours). The maximum is 30 days.

• SAML authentication validity period is the expiry window written into each issued assertion, which the service provider checks when it receives one. Keep this short. The default is 3600 seconds (one hour). The maximum is 24 hours.

To require a sign-in for every launch of the application, regardless of these timers:

1. Go to the Details tab.

2. Scroll down to the end of the Security section, and turn on Force re-authentication.

   

3. Select Save.

Sign and encrypt assertions

Link to this section

The Security section of the Details tab controls how Kinde protects each assertion it sends.

• Sign assertion is on by default and should stay on. It lets the service provider verify the assertion came from Kinde.
• Encrypt assertion is off by default. Turn it on if the service provider requires encrypted assertions, and paste its SP encryption certificate.

The SP encryption certificate is required when Encrypt assertion is on.

Configure single logout

Link to this section

Single logout is also configured in the Security section of the Details tab.

1. Set the SP logout callback URL. This is the third-party application’s endpoint where Kinde sends the logout response. Leave it blank to use the RelayState from each logout request.
2. Set the Single logout binding to match what the service provider expects.
3. If the tool publishes a signing certificate separate from its encryption certificate, add it as the SP signing certificate. Kinde uses it to verify signed requests coming from the application, such as logout requests.
4. Select Save.

The SP logout callback URL is the third-party application’s endpoint, not Kinde’s single logout URL. Kinde’s own single logout URL is on the IdP metadata tab and belongs in the third-party tool’s configuration.

Set an explicit callback URL where you can

RelayState arrives with each logout request rather than from your own configuration. If you leave the SP logout callback URL blank, make sure the service provider validates the RelayState value against its own allow list before treating it as a redirect target, otherwise it can be used to send people to an arbitrary destination after logout.

Delete an application

Link to this section

Deleting a SAML application is a destructive action that cannot be reversed. Its configuration, attribute mappings, access rules, and session records are removed, and anyone using it loses access.

1. Go to Settings > Environment > Applications and select the Workforce identity tab.
2. Select the three-dot menu next to the application you want to delete and select Delete.
3. Confirm the deletion by checking the box Yes, I definitely want to delete.
4. Select Delete.

Troubleshooting

Link to this section

People cannot sign in; they see an access denied message.

Check the Access control tab. If role-based access control is on, confirm the person holds one of the allowed roles in the organization they are signing in from.

The signing certificate field is empty.

The certificate is generated on first use. Select Test SSO, or complete a real sign-in.

The service provider rejects the assertion.

Confirm the SP entity ID and ACS URL match the tool exactly, and that the attribute names on the Attribute mapping tab match what the tool expects, including case.

The tile does not appear in the self-serve portal.

Confirm Show on self-serve portal is on, that the person’s organization is allowed under Limit to organizations, and that the Applications portal module is enabled.