Domain Whitelabeling for Identity Management

Domain whitelabeling allows you to customize the Identity Management authentication domain for social login, browser credential saving, and potential tracking or script blocking, providing a seamless user experience within your own domain.

Prerequisites

• Access to your DNS provider or domain registrar account

• Identity Management integration script implemented on your website

Step 1: Add DNS TXT Records for Authentication

To initiate the whitelabeling process, you will need to add new DNS TXT records for authentication.

This process requires Piano involvement, and you can contact our Piano Support at support@piano.io to initiate the whitelabeling process.

Afterward, follow these steps:

1. Log in to your DNS provider or domain registrar account.

2. Add the following DNS TXT records (replace the values with the ones provided by Piano Support):

   • Record 1: auth.yourdomain.com TXT your-authentication-token

   • Record 2: _cf-custom-hostname.auth.yourdomain.com TXT your-authorization-token

   Replace auth.yourdomain.com with your desired subdomain for whitelabeling that was provided to Piano.

   Note: Make sure to obtain the authentication token and authorization token values from Piano Support as described above.

3. Save the changes and allow some time for the DNS records to propagate. This process usually takes less than 24 hours.

Step 2: Replace DNS TXT Records with CNAME

After the DNS TXT records have been added and the authorization process is complete, you can replace them with a CNAME record. Follow these steps:

1. Once the DNS TXT records are propagated, replace them with a CNAME record.

2. Replace the DNS TXT records with the following CNAME record:

   • auth.yourdomain.com CNAME auth-piano-domain.tinypass.com

   Replace auth.yourdomain.com with your whitelabeled subdomain (if not otherwise specified by Piano Support).

Step 3: Update Authorized Javascript Origins

To ensure secure authentication, update the authorized JavaScript origins in the Identity Management settings. Follow these steps:

1. Access the Identity Management settings in your Piano dashboard.

2. Navigate to Edit Business → User Provider → Identity Management → Authorized tab

3. Update the authorized JavaScript origins to the following:

   • https://auth.yourdomain.com

   Replace auth.yourdomain.com with your whitelabeled subdomain.

To enhance security and prevent account takeover vulnerabilities, it is mandatory to add the top domain for whitelabeling as a redirect URI in the Identity Management Configuration under the Authorization tab.

Step 4: Update Identity Management Integration Script

To ensure proper functionality, you need to update your Identity Management integration script. Follow these steps:

1. Locate the Identity Management integration script on your website (or in the Piano dashboard under Products → Composer → Integrate → Edit Source).

2. Add or replace the following line in your integration script:

   • tp.push(['setPianoIdUrl', 'https://auth.yourdomain.com/']);

   Replace auth.yourdomain.com with your whitelabeled subdomain.

   The https:// prefix is required when setting the Identity Management URL, so make sure to include it, as shown in the example.

Step 5: Change the Deployment Host

Update the deployment host of your application by following these steps:

• Navigate to Edit Business → User Provider → Identity Management → Other Login Methods

• Update the Deployment Host to the whitelabeled subdomain.

Step 6: Update Social Login Authorized Redirect URI

To enable social login functionality, update the authorized redirect URI in the dashboards of the social platforms you integrate with Identity Management. Follow these steps:

1. Access the dashboard of each social platform (e.g., Google, Facebook).

2. Locate the authorized redirect URI settings.

3. Update the authorized redirect URI to the following:

   • https://auth.yourdomain.com/id/api/v1/identity/login/social/callback

   Replace auth.yourdomain.com with your whitelabeled subdomain.

Step 7: Google CAPTCHA Registration (Recommended)

If you have enabled reCAPTCHA v3, we recommend registering your own domain for Google CAPTCHA. More information about this feature is available here.

Final Steps

After completing the above steps, the whitelabeling process for your domain is complete. Users will now experience a seamless authentication process within your own domain.

Note: Whitelabeling the domain is typically meant for Production environments only.

Refer to this guide for comprehensive documentation on full domain whitelabeling.

Last updated: July 03, 2026