Auth Hosting Application

The Descope Auth Hosting App is a React application designed to easily host and run your Descope Flows, without requiring any implementation of our client SDKs in your application. This hosted app is also used by default when Descope is acting as an OIDC or SAML provider.

This application is traditionally hosted by us at https://auth.descope.io, or on your own domain, if you've configured a CNAME. Also, this app can be hosted by yourself and modified to use things like tenant and flow inputs, if needed.

Note

When utilizing Descope auth hosting with a custom CNAME, the URL slightly differs from https://CNAME/__ProjectID__?flow=<Flow_ID>.

You also need to include /login within the URL like: https://CNAME/login/__ProjectID__?flow=<Flow_ID>.

Key Features

Customizable Flows: Run any Descope flow by specifying the flow query parameter, including flows like sso-config. This enables you to tailor the authentication process to meet specific application scenarios and provide Tenant admins with a way of configuring their own SSO.
CNAME Configuration: If on Pro or Enterprise, you can integrate the Auth Hosting App with your domain for a branded authentication experience.
Dynamic Backgrounds: Optionally, change the app's background color dynamically using the bg query parameter, allowing for a seamless integration into your application's design scheme.
Flow Inputs: Optionally, be able to pass in specific tenant information using the tenant query parameter, providing a personalized authentication experience for users of specific tenants. Other attributes can be passed in as well, if hosting yourself.

This is an example of what the auth hosting application will look like:

Usage

To use the Auth Hosting App you will need to append your Project ID, which can be found under [Project Settings], to the end of https://auth.descope.io/<YOUR_PROJECT_ID. If you wish to use a custom domain, configure the CNAME under your [Project Settings], and the app will automatically utilize your own custom domain. When deploying or integrating the app, use the following query parameters to customize the authentication experience:

flow: Specifies which authentication flow to run. Example: ?flow=login.
bg: Changes the background color. Example: ?bg=ffffff.
tenant: If your project uses multi-tenancy, specify the tenant. Example: ?tenant=example_tenant.
debug: Allows you to see more in-depth flow errors in the console.
style: Allows you to run a specific style for your specific application.
theme: Allows you to enforce a specific theme for your Flows.

When applications redirect to Descope (as their SSO provider), they will then be taken to the page you've configured as your Flow Hosting URL. Therefore, using Descope as an OIDC / SAML provider, such as with Auth.js or with other Applications, you will need to configure the Flow Hosting URL under each app to be https://auth.descope.io/<YOUR_PROJECT_ID?flow=<Your Flow ID>.

Favicon

You also have the ability to set the favicon if you are using the Default OIDC application. Currently, this is set to Descope's favicon on the page but can be customized in auth-hosting per customer.

To change the icon, click on the pencil icon and upload your image.

Note

The file size of the icon cannot exceed 1MB.

This way you have an option to edit the default Descope OIDC Application's icon and set it as your own customized favicon.

Styling Per Application

If you're using Applications with OIDC/SAML, you can utilize the style and theme URL parameters in your Flow Hosting URL to adjust the styling of your flows for each application. Learn more about it here

Host the App Yourself

As an alternative option, you can host the app yourself with Vercel or some other hosting service. In the main README, you will find a deploy to Vercel button that can basically deploy a version of this app almost instantaneously in Vercel. You can also clone this repo as a template and deploy with AWS, Netlify, or DigitalOcean.

This is the recommended approach if you want to edit the application in any way that cannot be done with the query parameters above. This includes if you want to input custom values into the flow from your frontend as documented here, or if you want to change the background image of the flow completely and not just the color.

To host the app locally, follow these steps:

Clone the app repository.
Replace the Flow Hosting URL in the Console with http://localhost:3000/<YOUR_PROJECT_ID>?flow=<YOUR_FLOW_ID>.
Run the app with yarn install and yarn start.

Your flow should appear automatically when you go to this URL: http://localhost:3000/<YOUR_PROJECT_ID?flow=<YOUR_FLOW_ID>.

Was this helpful?