Custom OAuth 2.0 connections

You can enable users to sign up and sign in using their credentials from any OAuth2- and Open ID connection- compatible identity provider. To set this up, you need access to your provider’s developer console and a little technical know-how. We recommend setting this up in a non-production environment first, to test the connection thoroughly.

Custom OAuth 2.0 and Open ID connections allow you to integrate with any compatible identity provider that isn’t natively supported by Kinde. This includes custom identity providers, enterprise solutions, or specialized authentication services.

OAuth 2.0 / OIDC provider requirements

Link to this section

Before connecting your custom OAuth2 provider, ensure it supports the OAuth2 authorization code flow and can provide user profile information including email address. The provider must also support HTTPS for all endpoints.

Disclaimer

The following steps are a guide to what needs to happen on the custom OAuth 2.0 identity provider side. You may need to adapt some steps to suit the way different providers are configured.

Step 1: Get the custom connection credentials

Link to this section

1. Navigate to your provider’s developer console or admin panel.

2. Create a new application or client.

3. Configure your application settings:

   1. Set the application type to Web Application or Confidential Client.
   2. Add your Authorized redirect URIs. These are your Kinde domain or custom domain callback URLs. For example, account.customdomain.com/login/callback. If you don’t have this, you can copy it from the Kinde connection and add it later.
   3. Configure the required OAuth2 scopes. At minimum, you’ll need scopes to access user profile information and email address. Common scopes are: openid, profile, email. Add any other provider-specific ones you want.
   4. Set any additional configuration options required by your provider. These might include key attributes or upstream parameters.

4. Complete all the required application details (noting that you may need to go through a verification process depending on your provider).

5. Save your application configuration.

6. Copy the following information, which is required to set up the Kinde connection:

   • Authorization URL: The authorization endpoint URL
   • Token URL: The token endpoint URL
   • User Info URL: The endpoint to retrieve user profile information
   • Client ID: Your IdP application client ID
   • Client Secret: Your IdP application client secret

Step 2: Set up the Kinde connection

Link to this section

1. Sign in to Kinde.

2. Go to the Settings page and select Authentication.

3. In the Social connections section, select Add connection.

4. In the window that opens, select Custom OAuth 2.0, then select Next.

5. Enter a Connection name for internal identification. If you maintain a lot of external connections, you might want to include the customer’s name.

6. Enter an External name. This is what appears on the sign up and sign in screens of your app.

7. Enter all the relevant URLs and credentials from the previous step in the corresponding fields:

   • Authorization URL
   • Token URL
   • User Info URL
   • Client ID
   • Client Secret

8. Choose the Client authentication method. This controls how client credentials are sent to the provider’s token endpoint during the OAuth2 authorization code exchange. The options are:

   • Client secret in body (default) — The client ID and client secret are sent as parameters in the POST request body. This is the most common method and works with most OAuth2 providers.
   • Client secret in header — The client ID and client secret are sent as a Base64-encoded Authorization: Basic HTTP header. Some providers (e.g., Vipps MobilePay) require this method.

   The default is Client secret in body. Check your identity provider’s documentation to determine which method is required. If authentication fails with one method, switching to the other may resolve the issue.

9. Enter any additional configuration options required by your provider (e.g., key attributes and upstream parameters).

10. In the Callback URL section:

11. If you use Kinde’s domain as your default, copy the Kinde domain URL.

12. If you use custom domains, select the Use custom domain instead switch.

13. If you have only one custom domain, copy the Custom domain URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in your app.

14. Scroll down to the Provider icons section where you can upload a custom icon for this connection. This icon will appear on the sign-up and sign-in screens of your app.

15. Select which applications to switch this on for. If you are in a prod environment, this makes the connection live.

16. Select Save.

17. Use the copied Callback URL to finish setting up the provider configuration, see below.

Step 3: Add the callback URL to your custom connection

Link to this section

1. Navigate to your provider’s developer console or admin panel.
2. Enter the callback URL you copied from the Kinde configuration window.
3. Save.

Test your custom OAuth2 connection

Link to this section

After configuring your custom OAuth2 connection, test it thoroughly in a non-production environment before going live. Verify that:

• Users can successfully authenticate
• User profile information is correctly mapped
• Email addresses are properly captured
• Any custom claims or attributes are accessible

Troubleshoot custom OAuth2 connections

Link to this section

If you encounter issues with your custom OAuth2 connection, here are some things to try:

1. Verify endpoint URLs: Ensure all endpoint URLs are correct and accessible
2. Check scopes: Confirm that your provider supports the required scopes
3. Validate callback URLs: Ensure all callback URLs are properly configured in the IdP application
4. Review user info response: Verify that the user info endpoint returns data in the expected format
5. Check client authentication method: If you receive 401 Unauthorized or invalid_client errors during sign-in, try switching the Client authentication method between “Client secret in body” and “Client secret in header” — some providers only accept one of these methods

For additional support, contact Kinde support or refer to your OAuth2 provider’s documentation.