Go live
To deploy your project to staging or production, some changes need to be made in order to ensure stricter security.
This “Go live” guide also applies to deploying a project to staging. In case you’re facing issues, please see Troubleshooting.
If you’ve successfully developed and tested your product locally or on a staging server, some changes need to made (some of these changes cannot be reversed for a Corbado project).
Prerequisites
- You will need to have a domain you own.
- 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:
- Project ID: Formatted as
pro-. This is passed to the web component during initialization. - 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).
We’re currently working on a “Go live wizard” that takes care of cloning the most important configuration values into the production project. Until it’s ready, you need to manually copy / set the configuration values (see the next steps).
2. Set final Relying Party ID
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).
Please also check this guide that helps you to determine your Relying Party ID (rpID).
3. Set final CNAME
3.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).
3.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.
3.3 When is a CNAME needed for go live?
3.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.
3.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.
3.4 Which CNAME to set?
The CNAME must be a subdomain (e.g. auth.acme.com) of your domain (e.g. acme.com).
3.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
- Login: Go to your domain provider and find DNS settings.
- 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. - Save: Apply/save changes
In the Corbado developer panel, you can enter the CNAME here.
3.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
3.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
It can take up to 5 minutes until Corbado has registered your CNAME.
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.
4. Update relevant URLs
Update Redirect URL, Application URL here and Webhooks URL here. These values can be changed later.
5. 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.
When testing locally you do NOT need to specify an origin like localhost.
6. 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.
7. Deploy your code
You’re now ready to deploy your code to your production server in the regular deployment process of your application.
8. Contact us
Please send us an email or Slack message and we’ll double-check your settings, do a quick security review and convert your project to production in %lt;12 hours (no charges in the free community plan).
We are also happy to help you with personal and non-commercial projects. Do not hesitate to contact us via email or Slack.