Go live

If you’ve successfully developed and tested your product locally or on a staging server, some changes need to be made (some of these changes cannot be reversed for a Corbado project).

​

Prerequisites

1. You will need to have a domain you own.
2. If you use Corbado’s session management, you will need to be able to add DNS records on your domain.

​

Configuring environment variables and API secrets

Ensuring the correct setup of configuration values, particularly when transitioning to a production environment, is crucial to avoid common deployment errors. It’s advisable to leverage environmental variables for this purpose. Most hosting platforms, including AWS, GCP, Vercel and Heroku, facilitate the easy addition of these values. For local development, utilizing a .env file is recommended, allowing for dynamic value assignment based on your environment. Below are the variables you’ll need to modify for Corbado:

1. Project ID: Formatted as pro-. This is passed to the UI components during initialization.
2. API secret : Formatted as corbado1_. It’s used to access Corbado’s Backend API.

​

1. Create production project

In the Corbado developer panel, we recommend that you create a new project to keep your development or staging project separate from the production project (to not mess up with development configuration on production).

​

2. Set final Relying Party ID and Application URL

Update the application URL to the match the production URL of our UI component (including path).

Set a final Relying Party ID here, where passkeys are bound to. Note that all passkeys you created and used during development and testing will not work anymore once this value is changed. That’s also why a later change in production is not possible anymore (as it would invalidate all existing, working passkeys in production).

​

3. Add authorized origins for production

Add a new authorized origin for your production application here. You can add more authorized origins later. You need to specify each origin that communicates with Corbado in a separate row.

The origin is the address of your website or application where you integrate Corbado and that the user sees in the browser (the browser URL).

You need to provide the protocol (e.g. https) and port (if it’s different than 80 for http or 443 for https). The path should be empty (thus no trailing ”/”), e.g.: https://www.acme.com for a live application.

​

4. Set final CNAME

​

4.1 What is a CNAME?

A CNAME, or Canonical Name record, is a type of DNS record that maps one domain name (an alias, e.g. pro-123456789.frontendapi.cloud.corbado.io) to another (the canonical name, e.g. auth.acme.com).

​

4.2 Why is a CNAME needed for go live?

A CNAME is crucial when using Corbado’s session management in live environments because it enables you to use a custom subdomain that points to <project ID>.frontendapi.cloud.corbado.io ensuring SameSite cookies work properly, which enhances the security. Moreover, it improves UX as users see a familiar URL in the browser.

​

4.3 When is a CNAME needed for go live?

​

4.3.1 You use Corbado’s session management

If you use Corbado’s session management you must set up a CNAME to establish trust with users (by showing them a URL in the browser that they expect from your service) and leverage enhanced security with SameSite cookies.

If you use your own session management, it might not be strictly necessary but still advised.

​

4.3.2 You use a native iOS or Android app

Although not needed to be working correctly, we recommend to set a CNAME also for your native iOS or Android app, because then you can update the Relying Party ID as well to your desires.

This is mainly due to UX reasons, as without CNAME, the Relying Party ID by default would be <project ID>.frontendapi.cloud.corbado.io which might be confusing for users if they see this Relying Party ID in a Touch ID / Face ID / Android biometrics modal / popup. To update the Relying Party ID to your desired value, you would need a CNAME which is a subdomain of your Relying Party ID.

​

4.4 Which CNAME to set?

The CNAME must be a subdomain (e.g. auth.acme.com) of your domain (e.g. acme.com).

​

4.5 How do I set up the CNAME for go live?

Setting up the CNAME depends on your domain provider. In general, the steps are the following

1. Login: Go to your domain provider and find DNS settings.
2. Add CNAME: Input a subdomain of your domain in “Name” (e.g. auth.acme.com). Set “Type” to CNAME. In “Value”, use <project ID>.frontendapi.cloud.corbado.io. Choose an approriate “TTL”, often default is fine.
3. Save: Apply/save changes

In the Corbado developer panel, you can enter the CNAME here.

​

4.6 Set CNAME in UI components and Backend SDKs

If you use our UI components or one of our Backend SDKs (e.g. for Corbado’s session management), you need to update the Frontend API URL to be the same like the defined CNAME (otherwise you could get a JWT validation error because the iss JWT claim would not match anymore). See details here:

UI components

Backend SDKs

​

4.7 How do I test if the CNAME is correctly set up for go live?

To verify the CNAME, run the following DNS test in a terminal.

dig cname <CNAME>

The result should be:

<CNAME>:        43200   IN      CNAME   <project ID>.frontendapi.cloud.corbado.io

Alternatively, you can use an online DNS lookup tool (e.g. MxToolbox or NsLookup.io) and search for your configured subdomain, which should point to <project ID>.frontendapi.cloud.corbado.io.

​

5. Create API secrets for production

If you’ve used one of Corbado’s Backend SDKs, you should create a new API secret here that is only valid for production in order to prevent the leakage of a development’s API secret.

​

6. Deploy your code

You’re now ready to deploy your code to your production server in the regular deployment process of your application.