Understanding Redirect URI and Authorization Code Flow in OpenID Connect (OIDC)

What is a Redirect URI?#

A Redirect URI, also known as a Reply URL, is a critical security component in OIDC authentication process. It specifies the URL where users are sent after successfully signing in through an OIDC provider. More importantly, it's where your application receives the authorization code needed to obtain tokens.

Check out the Redirect URI wiki for more details.

What is the Authorization Code Flow?#

The Authorization Code Flow (defined in OAuth 2.0 RFC 6749, section 4.1) is a fundamental authentication method in OIDC. It involves exchanging an authorization code for an access token and, optionally, a refresh token. This flow is suitable for applications that can securely maintain a client secret, such as server-side web applications.

Check out the Authorization Code Flow wiki for more details.

How does the Redirect URI work in the Authorization Code Flow?#

In the Authorization Code Flow, the Redirect URI is the destination to which the OIDC provider sends the authorization code after the user successfully authenticates. It must be pre-registered with the OIDC provider to ensure security and prevent unauthorized redirections.

Here's how you can register a Redirect URI in Logto Console:

When initiating a sign-in:

1. Authorization request: Your application directs the user to the OIDC provider's authorization endpoint, including parameters like client_id, response_type, scope and the redirect_uri.
2. User authentication: The user authenticates with the OIDC provider.
3. Authorization code delivery: Upon successful authentication, the OIDC provider redirects the user to the specified redirect_uri, including an authorization code as a query parameter.

The OIDC provider validates the redirect_uri against the list of pre-registered URIs. If there's a mismatch, an invalid_redirect_uri error will be returned, enhancing security by preventing unauthorized endpoints from receiving tokens.

Best practices for Redirect URIs#

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 https://my-app.com, then usually the redirect URI would be declared as https://my-app.com/callback

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

Other best practices include:

• Avoid wildcards: Do not use wildcard patterns in redirect URIs. Explicitly list all allowed URIs to prevent unauthorized access.
• Match exactly: Ensure the redirect URI matches exactly with the one registered in the OIDC provider. Even a trailing slash can cause a mismatch.

Handle sign-in callback#

To handle the authorization code returned to your redirect_uri, follow these steps:

1. Extract the authorization code: Retrieve the code parameter from the query string of the redirect URI.

2. Exchange the authorization code for tokens: Compose a POST request to the OIDC provider's token endpoint, including:

   • client_id: The ID of your application in the OIDC provider
   • code: The authorization code received from the redirect URI
   • code_verifier: A random string generated on the client
   • redirect_uri: The same URI used in the authorization request
   • grant_type: The type of grant, usually authorization_code

Sample token exchange request in JavaScript#

Simplify code exchanging process in Logto by leveraging the 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:

SDK integration guides can be found on the Logto quick-starts docs.

Recap: why it is important to master Redirect URIs in OIDC#

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.