Redirect URIs and Their Use Cases

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

Introduction

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.

SP Initiated

With an SP initiated login flow, where a user begins the authentication process from your application, it’s a common practice to route requests from different Organizations to one Redirect URI and utilize the State parameter to determine where the requests get routed to after authentication. The State parameter is an optional parameter that can be included when making the Get Authorization URL call which will persist through the login flow. In this case, developers may use the State parameter to deep link users into an application after the authentication is completed.

Get Authorization URL Call

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('sk_example_123456789');
workos.sso.getAuthorizationURL({
organization: process.env.WORKOS_ORGANIZATION_ID
clientID: 'client_123456789',
redirectURI: 'https://your-app.com/callback',
state: 'dj1kUXc0dzlXZ1hjUQ==',
});

IdP Initiated

Although IdP initiated SSO is supported by WorkOS, it is not the recommended approach as there are inherent risks that come along with it. Because IdP-initiated SSO involves unsolicited SAML Responses, it is susceptible to man-in-the-middle attacks. An attacker could steal the SAML assertion and log in to your application as the user initially trying to authenticate. We recommend using SP-initiated SSO wherever possible.

On top of the security concerns, configuring Redirect URI’s is also little bit trickier when dealing with an IdP-initiated login flow, where the login flow starts by clicking on a tile within the IdP like in the screenshot below.

The reason that it’s more difficult is because with an IdP initiated flow, there is no way to send along additional information when the login flow is launched. With an IdP initiated login flow, the default Redirect URI will always be used. There is no opportunity to programmatically specify a Redirect URI or a State parameter to differentiate between unique Organizations.

While there is no unique Redirect URI or State Parameter that can be used to route the requests, you will have access to the Profile object Profile object that gets returned after the authentication is completed.

Example of Profile Object

{
"id": "prof_01DMC79VCBZ0NY2099737PSVF1",
"connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
"connection_type": "okta",
"email": "[email protected]〖foo-corp.com〗",
"first_name": "Todd",
"idp_id": "00u1a0ufowBJlzPlk357",
"last_name": "Rundgren",
"object": "profile",
"raw_attributes": {...}
}

This object will include the connection_id that the profile is associated with in WorkOS. We recommend that this is the piece of information that be used for routing requests in an IdP Initiated scenario.

Wildcard Characters

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.