WorkOS Docs Homepage
Single Sign-On

Redirect URIs and Their Use Cases

Learn what a Redirect URI is and how it relates to Service Provider and Identity Provider Initiated Login.

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 Configuration 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.

  • The protocol of the URL must be either http: or https:. For example, com.example.app://*.example.com will not work.
  • The wildcard must be located in a subdomain within the hostname component. For example, http://*.com will not work.
  • The wildcard must be located in the subdomain which is furthest from the root domain. For example, https://sub.*.example.com will not work.
  • The URL must not contain more than one wildcard. For example, https://*.*.example.com will not work.
  • A wildcard character may be prefixed and/or suffixed with additional valid hostname characters. For example, https://prefix-*-suffix.example.com will work.
  • A URL with a valid wildcard will not match a URL more than one subdomain level in place of the wildcard. For example, https://*.example.com will not work with https://sub1.sub2.example.com.