Redirect URIs

With a WorkOS Service Provider (SP) initiated login flow, there are a series of exchanges that take place between a Service Provider (your application), WorkOS, and the IdP that’s being used to authenticate the user as shown in the diagram below. The Redirect URI is the location to which the user gets returned to after successfully completing the authentication with their Identity Provider (IdP).

With an Identity Provider (IdP) initiated login flow, the approach is similar but the user will begin the login flow by clicking on the tile within their IdP platform instead of from your application.

In WorkOS Production Environments, the Redirect URI to your application must use HTTPS, however, Redirect URIs that use HTTP and localhost are allowed in Sandbox Environments.

There should be at least one redirect URI configured and selected as a default for a WorkOS Environment. This can be done from the Redirects page in the WorkOS dashboard. If you try to route the authorization flow to a Redirect URI that is not yet defined in the Dashboard it will result in an error and users will be unable to sign in, so it’s important to define them in the dashboard first.

The Redirect URI can also be included directly in the Get Authorization URL call as a redirect_uri parameter. When the Redirect URI is set in this fashion, it will override the default Redirect URI that is set in the WorkOS Dashboard.

WorkOS supports using wildcard characters in Redirect URIs for staging environments.

The * symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at User Management, a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.