Custom OAuth 2.0 connections

You can enable users to sign up and sign in using their credentials from any OAuth2-compatible identity provider. To set this up, you need access to your OAuth2 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 connections allow you to integrate with any OAuth2-compatible identity provider that isn’t natively supported by Kinde. This includes custom identity providers, enterprise solutions, or specialized authentication services.

OAuth 2.0 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 OAuth2 provider’s developer console or admin panel.

2. Create a new OAuth2 application or client.

3. Configure your OAuth2 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 OAuth2 authorization endpoint URL
   • Token URL: The OAuth2 token endpoint URL
   • User Info URL: The endpoint to retrieve user profile information
   • Client ID: Your OAuth2 application’s client ID
   • Client Secret: Your OAuth2 application’s 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. Enter any additional configuration options required by your provider, e.g. key attributes and upstream parameters.

9. In the Callback URL section:

   1. If you use Kinde’s domain as your default, copy the Kinde domain URL.
   2. If you use custom domains, select the Use custom domain instead switch.
   3. 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 OAuth2 app.

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

11. Select Save.

12. Use the copied Callback URL to finish setting up your OAuth2 app, see below.

Step 3: Add the callback URL to your custom connection

Link to this section

1. Navigate to your OAuth2 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’s some things to try.

1. Verify endpoint URLs: Ensure all OAuth2 endpoint URLs are correct and accessible
2. Check scopes: Confirm that your OAuth2 provider supports the required scopes
3. Validate callback URLs: Ensure all callback URLs are properly configured in your OAuth2 application
4. Review user info response: Verify that the user info endpoint returns data in the expected format

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