Introduction

This guide will cover the end-to-end configuration necessary for configuring Descope to manage sessions in cookies by configuring a custom CNAME for your Descope project.

Note: Configuring a Custom Domain is a pro-tier feature. Learn more about upgrading your tier within our pricing overview.

Descope recommends storing your refresh tokens in cookies rather than within browser local storage. Keeping the refresh token in cookies is essential because it will help mitigate the risk of XSS (Cross-site-scripting) attacks since tokens in local storage are accessible via JavaScript. Descope uses httpOnly cookies in order to make the refresh token inaccessible to JavaScript, protecting your users from XSS and other browser-based attacks. Descope cookies are also sameSite=strict, so they are only sent in a first-party context, ensuring 3rd party websites cannot impersonate/hijack the user with a CSRF attack.

By default, your Descope project is configured to manage tokens in the HTTP response body; while this allows for a quick start at development, it is highly recommended to handle tokens in cookies for the above mentioned reasons.

Due to the nature of sameSite=strict, the domain used for the cookie must be a subdomain of your website, requiring you to configure a DNS setting for your website to allow using Descope API with your domain.

The sameSite and domain configurations are covered within this knowledge base guide.

Note: If you're looking for a list of what values in the Descope Console are affected by Custom Domains, scroll down to our Affected Settings page.

Configure Custom CNAME

This section assumes you are not sharing the cookie with multiple subdomains. This guide is still applicable; however, the record will differ; for more information, see the section for Sharing Cookies Across multiple Subdomains. For this guide, the application lives at the domain app.example.com.

Create a DNS Record

Within your DNS settings for your host, create a DNS record for auth.app.example.com, which points to:
  1. US projects - cname.descope.com.
  2. EU projects - CNAME.euc1.descope.com.

  • Record Name: auth.app.example.com
  • Type: CNAME
  • TTL: Keep as default
  • Record Data/Value: cname.descope.com / CNAME.euc1.descope.com

Descope custom domain cname host record.

Configure App URL

Within the Project Settings, under General, enter your app URL ex: https://app.example.com.

Descope configure custom domain cname within Descope project.

Configure Custom Domain

After adding the App URL, you will see the Configure Custom Domain section. Here you will click the Add button to add the Custom Domain to this project, for this example, it is app.example.com. This should match the configured DNS Record you created within your application.

Descope configure custom domain cname within Descope project.

Verify Domain configuration

Once the domain has been added, you will see Custom domain is pending verification under the domain. Periodically click the Refresh button until you see Setup complete.

The Descope console will also provide you with code snippets to use within your frontend to set the base URL to the configured custom domain, this will be used in the next step.

Descope configure custom domain cname within Descope project.

Configure Project to Manage Tokens in Cookies

Within the Project Settings, under Session management, select Manage in Cookies, then select the configured domain from the Cookie Domain dropdown. Select Strict from the Cookie Policy dropdown, then save the configuration.

Descope configure custom domain cname within Descope project.

Update the Base URL within Your Code

Within your code, use the record's base URL configured in step 1, auth.app.example.com, when utilizing the Descope Frontend SDKs or flows.

Here are some examples of configuring the base URL when initializing the client SDK.

ReactHTML/WebJSNextJs 
<AuthProvider projectId='__ProjectID__' baseUrl='https://auth.app.example.com'>
<descope-wc project-id="__ProjectID__" base-url="https://auth.app.example.com" flow-id="sign-up-or-in"></descope-wc>
<AuthProvider projectId='__ProjectID__' baseUrl='https://auth.app.example.com'>

Test Cookie Storage

Test your Descope login flow. The DS, which is the Descope Session JWT, will be stored within the local storage, and the DSR, which is the Descope Session Refresh JWT will be stored under cookies for https://app.example.com

For testing cookies within a local environment, see this knowledge base guide.

Using Custom Domains for OAuth Applications

Once you have configured the CNAME within your environment, you can utilize the custom domain within the OAuth applications when using your account. Based on the example above, within the configuration for the OAuth application, you will configure the custom domain with auth.app.example.com as shown in the below screenshot.

Descope custom domain for OAuth.

Sharing Cookies Across multiple Subdomains

The configuration is slightly different if you’d like to share cookies across multiple subdomains. When configuring the DNS record for this use case, the record name will be auth.example.com

Then within the Descope console, the Custom domain will be example.com instead of app.example.com within the project configuration, as you need to set the cookie at the topmost level of the domain.

Example

Below covers an example of configuring the CNAME and cookie settings for both strict cookies and shared cookies across subdomains.

  • Company: example.com
  • App: app.example.com
  • Docs Site: docs.example.com
SettingStrict (not shared)Shared with docs
CNAMEauth.app.example.comauth.example.com
Cookie Settingsapp.company.comcompany.com
Base URLhttps://auth.app.example.comhttps://auth.example.com

Affected Settings

When configuring a custom domain in the Descope Console, several settings are directly impacted by this configuration. Understanding how each setting is affected is crucial for successful integration and functionality of your Descope project.

Many of these settings are also documented above in the rest of the guie, but this is an overview of all of the affected settings when you configure custom domains:

  1. Approved Domains: These are the domains that are authorized to interact with your application (within the context of Descope SDK and API usage). Setting a custom domain here ensures that authentication requests are limited to your specified domains.
Approved domain with custom domain.
  1. Cookie Domain: This determines the domain scope for your refresh token stored in cookies. When you set a custom domain for your cookies, it ensures that refresh tokens are tightly bound to your specified domain and application.
Cookie Domain for refresh token with custom domain.
  1. OAuth Callback URL and Callback Domain: These are the redirect URL and callback domain used during OAuth flows. With a custom domain configured, the callback URL will reflect your specified domain where the OAuth code will be returned, which will need to be configured in your OAuth provider (e.g. Google, Facebook, etc.).
Descope custom domain for OAuth.
  1. Passkey Top-Level Domain: When using passkeys, the top-level domain is critical for proper routing and authentication. A custom domain ensures that passkeys are associated with your specific domain, thereby enhancing the security and integrity of passkey authentication.
Passkey top level domain.
  1. Base URL: This is the fundamental URL for the Descope SDK to be able to work with the underlying APIs. Setting a custom domain here ensures that all API interactions between your app with the Descope SDKs occur through your specified domain.
Base URL for Custom Domain.
  1. SAML ACS URL (in SAML SP Configuration for Tenants): This URL is used for SAML assertions. Customizing it to your domain ensures that SAML responses are correctly directed and handled, which is vital for secure and efficient SAML authentication.
SAML ACS URL with custom domain.

Configuring these settings correctly with your custom domain is essential to maintain the security, functionality, and user experience of your Descope project.