Understanding Redirect URIs in OIDC with Authorization Code Flow

Background

In a previous post (How PKCE protects the authorization code flow), we delved into the Proof Key for Code Exchange (PKCE) flow in OIDC, and explored why it has gained widespread adoption, particularly among single-page web apps and native mobile apps. We have also talked about an Expo vulnerability that impacts hundreds of online services, because of a mis-handling of the redirect URI.

Well, both these articles mentioned redirect URI, and it's essential for security. But what exactly is it? How can we handle it properly in Logto?

Today, let's take a closer look at the redirect URI as it's crucial for app developers and system administrators.

Understanding redirect URI in authorization code flow

In the Authorization Code Flow, a key component is called Redirect URI. It is the URL where a user is navigated to after they authenticate themselves successfully . It's also the place where the user's ID token and access tokens are delivered.

The redirect URI can be one of a set of URIs that are pre-registered in the OIDC server. In the Logto Console, go to “Applications” to create or select an existing application entity (SPA or native app type), and in the creation guide or the application details page, you can set one or multiple redirect URIs.

When a client app initiate a sign-in action, an “authorization request” is made and it will carry the necessary parameters to the OIDC server, including the redirect URI. The OIDC server will check if the redirect URI received in the authorization request matches to the pre-registered set of redirect URIs. If the URI does not match to any of the registered URIs, a “invalid_redirect_uri” error will be thrown.

In real life use cases, a common best practice is to declare a dedicated “Callback” page and associate a router / deep link that allows direct access from external. This link should be used as the redirect URI.

Assuming you have a single-page web app that is running on http://localhost:3000, then usually the redirect URI would be declared as http://localhost:3000/callback

Or if it is an native mobile app, and then the redirect URI deep link usually starts with a custom scheme, e.g. com.company://myapp/callback

This registration process acts as a safeguard, ensuring that only trusted and pre-authorized URIs are allowed. Developers can specify multiple redirect URIs for the same application, in order to have the flexibility and compatibility with different environments and use cases.

Handle sign-in callback

When your app is redirected to the “Callback” page by the OIDC server upon a successful sign-in, a “code” string will be generated by OIDC server and carried over through URI parameter.

Then in your application, implement the following operation in the “Callback” page in order to fetch the the ID token and access token:

1. Retrieve the “code” string from URI parameter
2. Compose a post request and send the “code” and other required parameters to the Token Endpoint as form url encoded content.

Here's a JavaScript sample that composes the POST request to exchange for the access token:

const parameters = new URLSearchParams();
/* The ID of the application in Logto Console */
parameters.append('client_id', clientId);
/* Code received from the redirect URI parameter */
parameters.append('code', code);
/* A random string generated on the client */
parameters.append('code_verifier', codeVerifier);
parameters.append('redirect_uri', 'http://localhost:3000/callback');
parameters.append('grant_type', 'authorization_code');

const { idToken, accessToken } = await post('https://auth.logto.io/oidc/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: parameters,
});

// Verify and save tokens to localstorage
// Then navigate to your home page or dashboard
...

Simplify everything by leveraging Logto SDKs

Logto SDKs are the development kit written in a specific programming language or framework, e.g. Logto React SDK, Next.js SDK and Swift SDK. Using an SDK can greatly simplify things up by just calling one or two functions.

Here's a React “Callback” component sample using the Logto official React SDK:

import { useHandleSignInCallback } from '@logto/react';

const Callback = () => {
  useHandleSignInCallback(() => {
    // Navigate to home or your dashboard page
  });
};

Full React sample project can be found here: https://github.com/logto-io/js/tree/master/packages/react-sample

Recap

Understanding Redirect URIs in OIDC with the authorization code flow is crucial for securing and optimizing your authentication processes. By registering trusted redirect URIs and handling sign-in callbacks efficiently, you can ensure a seamless and secure experience for your users while simplifying your development efforts with Logto SDKs.