Configuring CNAME and Managing Sessions in Cookies

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.

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 cname.descope.com.

  • Record Name: auth.app.example.com
  • Type: CNAME
  • TTL: Keep as default
  • Record Data/Value: cname.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