A redirect URI is simply the web address where Okta sends the user’s browser once sign-in is finished.

The plain-English meaning

URI stands for Uniform Resource Identifier. For everyday purposes you can read it as “a web address.” A redirect URI is the address of a page or a route inside your application that is ready to receive the result of a login. When a user clicks “Sign in” in your app, the browser leaves your app, travels to Okta, the user types a password or approves a prompt, and then the browser has to come back. The redirect URI is the “come back here” address.

You will also hear it called a callback URL, a login redirect URI, or a sign-in redirect URI. In the Okta Admin Console the field is labeled “Sign-in redirect URIs.” All of these names point to the same idea, so do not be confused when documentation, blog posts, and other vendors use different words.

What travels back to that address

When Okta redirects the browser, it attaches a small amount of information to the address. In the most common and recommended pattern, this is a short-lived authorization code and a value called state. Your application takes the code and exchanges it, behind the scenes, for the real tokens. The user never sees this exchange, but it is the heart of modern single sign-on.

Why this one address matters so much

Whoever controls the redirect URI receives the code. If an attacker could trick Okta into sending the code to an address the attacker owns, the attacker could impersonate the user. That is why Okta, like every well-built identity provider, refuses to send anything to an address that has not been registered ahead of time.

The registered list is a safety fence, not a formality.

The allow-list idea

Every application that talks to Okta over OpenID Connect (OIDC) or OAuth 2.0 is represented inside Okta by an app integration. Inside that app integration, you keep a list of approved redirect URIs. Each time your app starts a login, it tells Okta which redirect URI it wants to use. Okta then looks at its list. If the requested address appears on the list exactly, the login continues. If not, Okta stops and shows an error instead of redirecting anywhere.

This is called an allow-list check. Allow-lists are popular in security because they fail safely: anything you forgot to list is blocked, rather than anything you forgot to block being allowed.

What attacks the list prevents

Without the list, an attacker could craft a login link that looks like it belongs to your company but secretly names an attacker-controlled address as the destination. A user who clicks it signs in genuinely, and Okta, trusting the request, delivers the fresh authorization code to the attacker. The registration list closes this door. Two well-known attack families are blocked this way: open redirect abuse and authorization code theft.

Who maintains the list

Usually it is the team that owns the application, often together with an Okta administrator. In larger companies the list is controlled by a platform or identity team, and application teams request additions through a ticket or an automated pipeline. Because a wrong entry can weaken security, many organizations treat changes to this list as a reviewed change rather than a casual edit.

Before configuring anything, it helps to know the vocabulary Okta uses.

How the pieces connect

Your Okta org contains many app integrations. Each app integration has one client ID, a set of sign-in and sign-out redirect URIs, and an assigned set of users or groups. Each app integration is also tied to an authorization server when it asks for tokens. Trusted origins sit beside all of this at the org level and apply to browser-based behavior.

graph TD
  ORG[Okta Org] --> APP1[App Integration: Web Portal]
  ORG --> APP2[App Integration: Mobile App]
  ORG --> TO[Trusted Origins]
  ORG --> AS[Authorization Server]
  APP1 --> RU1[Sign-in Redirect URIs]
  APP1 --> SO1[Sign-out Redirect URIs]
  APP1 --> CID1[Client ID]
  APP2 --> RU2[Sign-in Redirect URIs]
  APP2 --> CID2[Client ID]
  AS --> APP1
  AS --> APP2
        

Seeing where the redirect URI is used makes every error message easier to read.

The recommended modern pattern is the authorization code flow, ideally with a safety extension called PKCE (Proof Key for Code Exchange, pronounced “pixie”). Here is the full journey in plain steps, and where the redirect URI appears in each.

sequenceDiagram
  participant U as User Browser
  participant A as Your Application
  participant O as Okta
  U->>A: Click Sign in
  A->>U: Redirect to Okta with client ID and redirect URI
  U->>O: Authorization request
  O->>O: Check redirect URI against registered list
  O->>U: Show login page
  U->>O: Credentials and MFA
  O->>U: Redirect to registered redirect URI with code
  U->>A: Arrive at callback with code and state
  A->>O: Exchange code for tokens
  O->>A: ID token and access token
        

The other pieces of the request

The redirect URI never travels alone. The authorization request also names the response type, which tells Okta that your app wants a code. It names the scopes, which describe what the app wants to know about the user, such as their identity or email. It carries the state value for protection against forged responses, and a nonce, which ties the identity token to this particular login. When the PKCE extension is used, it also carries a challenge and a method. Think of the redirect URI as the return address written on an envelope that also contains a short letter explaining everything else the sender wants.

What happens when something goes wrong after login

Not every failure happens at the redirect check. Sometimes the user cancels, a policy denies the login, or a requested scope is not allowed. In these cases, once the redirect URI has been accepted as valid, Okta can safely send the browser back to it with an error description instead of a code. Your callback route must therefore be ready for both outcomes: a success with a code and a failure with an error. A callback that only understands success will show a blank page or crash whenever a user presses cancel, which feels like a bug in the login even though Okta behaved correctly.

The setting lives inside the app integration, in the Admin Console.

Menu names in Okta change from time to time, so treat the following as a reliable map rather than a word-for-word script. If a label looks slightly different on your screen, look for the closest match.

Plan before you click

The cleanest configurations start on paper. Before opening the console, write down four facts. First, which type of application is this: server website, browser app, phone app, or backend service? Second, which environments will use it, and what is the web address of each one? Third, which exact route in the app receives the login result? Fourth, does the app support logout redirection, and if so, which page should users land on afterwards? With those four answers in hand, the console work takes minutes and the chance of a typo drops sharply.

It also helps to decide who is allowed to edit the integration. Okta supports different administrator roles, so a developer can be given rights to manage only certain applications rather than the whole org. Limiting rights this way keeps accidental edits away from critical production integrations.

Configuring an existing application

Creating a new application

When you create a new app integration, Okta asks you to choose a sign-in method and an application type, such as web application, single-page application, or native application. The type you choose changes the default settings, especially which grant types are enabled and whether a client secret is created. After you pick the type, the creation screen presents the redirect URI fields directly, so you can add the first addresses at the same time.

Configuring through automation

Many teams do not click through the console for every change. Okta offers an administration API, and there are infrastructure-as-code tools and pipeline integrations that manage app integrations for you. Using automation gives you a written history of who changed which redirect URI and when, and it lets a reviewer approve the change before it reaches production.

Okta stores several kinds of addresses, and each has a different job.

New learners often add every address into the sign-in field and wonder why logout or other flows still fail. The three most common address types are different on purpose, and the table below shows how.

Sign-in redirect URIs in more detail

You can register several sign-in redirect URIs on one app integration. Your app chooses one at request time. This is how one integration can serve both a main website and a secondary admin area, for example. Keep the list short, though. Every entry is a place where login results may land, so each one deserves a reason to exist.

Sign-out redirect URIs in more detail

When your app logs the user out of Okta, it can ask Okta to send the browser to a specific page afterwards. That page must also be on the registered sign-out list. If you forget it, the user is logged out but then sees an error, which feels broken even though the logout itself worked.

Initiate login URI in more detail

Sometimes a user begins in the Okta dashboard by clicking your app’s tile. In that case Okta, not your app, starts the journey. Okta needs to know which address of your app should kick off a proper login. That address is the initiate login URI. Your app receives the visit and then starts its normal sign-in request.

Most failures come from tiny differences that are easy to overlook.

Exact matching

The central rule is exact matching. The address your app sends must match one registered entry character for character. It is not a “close enough” comparison. Each of the following differences makes a new, different address in the eyes of Okta.

Secure transport

For any address that is not on your own machine, Okta expects https. Plain http is accepted for localhost during development, because traffic never leaves your computer. For real environments, use https always, so that the code in the address cannot be read by someone on the network.

No fragments

An address may not include a fragment, which is the part that begins with a hash symbol. The specification forbids it, since fragments are never sent to servers and would create confusion about where results are delivered.

The type of application changes what a good redirect URI looks like.

Naming mobile callbacks well

For phone apps, the convention is to build the custom scheme from your company’s reversed domain name, followed by the app name. This makes accidental collisions with other companies unlikely, because nobody else owns your domain. The path after the scheme is usually a short word such as callback. Keep the same value in the Okta list, in the app’s platform configuration file, and in the software library that handles the login. Three places, one value. If any of the three drifts, the login either fails at Okta or the phone cannot find your app to hand the result back.

Verified https links, known as universal links on one platform and app links on the other, are the stronger option. The operating system checks that your website and your app belong together before it routes the link, so another app cannot quietly intercept the result. They take more setup, since your website must publish a verification file, but they remove an entire class of hijacking risk.

Real teams run more than one copy of every application.

A typical company runs a developer’s laptop, a shared development server, a testing environment, a staging environment, and production. Each of these has its own web address, and therefore each needs its own redirect URI. How you organize that in Okta is a design decision with trade-offs.

Option one: one Okta org, one integration per environment

You keep a single Okta org but create a separate app integration for each environment. Each integration has its own client ID and only the redirect URIs for that environment. Production never contains a localhost entry, and a developer cannot accidentally sign in to production through a test address. This is the clearest and safest setup in a shared org.

Option two: separate Okta orgs

Larger companies often use a completely separate Okta org for non-production work, with a preview or sandbox tenant for testing. This gives strong isolation of users, policies, and settings. The cost is that you must keep the two orgs aligned so that what you test is what you ship.

Option three: one integration with a long list

The shortcut is to put every environment’s addresses into one integration. It works, but it blurs boundaries. A test address living beside a production address in the same app integration is a risk that grows with time, because people forget what each entry is for.

Keeping environments in step

The hardest part of running several integrations is not creating them, it is keeping them aligned. Over months, a setting changed by hand in the test integration may never reach staging, and the difference only appears when a release behaves differently in production. Teams reduce this risk by describing the integration in a written, versioned form and applying it to each environment with the same automation. The only values that should differ between environments are the ones that must, namely the web addresses and the client identifiers.

A simple promotion habit also helps. When a new route or domain is added, register it in development first, then testing, then staging, then production, in that order, and record each step in the change ticket. The sequence gives everyone a chance to catch a typo while the stakes are low.

flowchart LR
  DEV[Developer Laptop] --> I1[Integration: Dev]
  TST[Test Server] --> I2[Integration: Test]
  STG[Staging] --> I3[Integration: Staging]
  PRD[Production] --> I4[Integration: Production]
  I1 --> ORG[Okta Org]
  I2 --> ORG
  I3 --> ORG
  I4 --> ORG
        

Convenience features exist, but each one has a safety cost.

Localhost during development

Developers need to run applications on their own computers. Okta allows localhost addresses over plain http for this reason. Remember that the port number is part of the address. If your development server moves from one port to another because the first was busy, your login will suddenly fail until you register the new port or restore the old one. Many teams agree on a fixed port for each project to avoid this.

Wildcards

A wildcard is a placeholder character that stands for “anything here.” It is tempting when you have many sub-sites, such as one per customer. Okta has historically treated redirect URI matching as exact, and wildcard behavior, where it exists at all, is an opt-in setting that Okta itself warns against using in production. Always check Okta’s current documentation for your app type before relying on any wildcard behavior, because the rules can change.

The risk is straightforward. A wildcard widens the fence. If an attacker can create a page anywhere inside the wildcard’s range, such as a user-generated sub-site, the code may be delivered there. A pattern like “any subdomain” is only as safe as your control over every subdomain.

Many tenants or customers

If your product gives each customer a custom sub-domain, the safest approach is usually a single shared callback address on a domain you control. After login, your own application then routes the user to the right customer area. This keeps the Okta list small while still supporting any number of customers.

Custom domains

Okta can serve its sign-in pages from your own custom domain. This changes the address your users see in the browser while they log in, but it does not change your application’s redirect URI. The redirect URI always describes where your app receives the result, never where Okta lives.

The redirect step is one of the most attacked parts of any sign-in system.

Authorization code interception

The code travels through the browser, in the address bar. On a phone, another installed app might register the same custom scheme and receive the code. In a browser, a malicious script or extension might read it. If the thief can trade that code for tokens, they become the user. PKCE solves this by tying the code to a secret that only your app knows. A stolen code is useless without the matching verifier.

Open redirect abuse

Suppose your application has a page that redirects visitors anywhere a parameter says. If that page is registered as a redirect URI, an attacker can chain the two: Okta sends the code to your page, and your page forwards the visitor, with the code still in the address, to the attacker’s site. This is why you should never register an address that can bounce users to arbitrary destinations.

Cross-site request forgery

An attacker may try to push their own login result into your user’s session. The state value defends against this. Your app creates a random state before leaving, remembers it, and checks that the returning state matches. If it does not match, the response is rejected.

Leaks through logs and referrer headers

The address that carries the code is just a web address, and web addresses are stored in many places. Browsers keep history, web servers write access logs, monitoring tools capture page views, and some analytics scripts copy the full address. If a code lingers in any of these, it becomes a small risk. Codes are short-lived and single-use, which limits the damage, but it is wise to keep the callback route lean, to exchange the code immediately, and to send the user onward to a clean address that no longer carries it. Avoid loading third-party scripts on the callback page, because they could read the address before your own code removes the code from it.

Redirect URIs and trusted origins work side by side, and beginners often mix them up.

What an origin is

An origin is the combination of scheme, host, and port, with no path. For example, https://app.example.com is an origin. Browsers use origins to decide which websites may talk to which servers. This browser rule is called the same-origin policy, and the controlled exception to it is called cross-origin resource sharing, or CORS.

Why Okta keeps a trusted origins list

When a single-page application calls Okta directly from the browser, Okta must decide whether that browser page is allowed to make the call. The trusted origins list answers that. Entries can be marked for cross-origin calls, for redirects, or both. A single-page app that signs in using a redirect usually needs its origin listed for both purposes.

How they fail differently

A missing redirect URI normally produces an error page at Okta before login begins. A missing trusted origin tends to appear in the browser as a blocked network call, often described in the developer console as a cross-origin failure. Knowing which of the two you are looking at saves hours of guessing.

A calm checklist is faster than guessing.

The most recognizable Okta error says, in essence, that the redirect parameter must be one of the sign-in redirect URIs set in the client app settings, and it usually repeats the address your app sent. That repeated address is the most useful clue you have. Compare it, character by character, with the list inside Okta.

Symptom guide

Using the browser to see what really happened

Your browser’s developer tools are the quickest way to see the real request. Open the network view before clicking Sign in, and watch the first request that goes to Okta. Its address contains every parameter, including the redirect URI as your app actually encoded it. Special characters are shown in a percent-encoded form, so a slash may appear as a short code. Decode it mentally, or paste it into a decoder, and compare it with the Okta list. Often the discovery is something simple, such as the app reading its address from an environment setting that still holds yesterday’s value.

Also watch the final request in the journey, the one that arrives back at your callback route. If it carries an error description instead of a code, read that description. It usually states the reason in plain words, and it saves you from searching in the wrong place.

What you cannot see, you cannot fix or defend.

The Okta System Log

Okta records activity in its System Log. When a sign-in request fails because of a redirect problem, the log typically records a failed authorization event with the reason and the application involved. Searching the log by application name or client ID quickly narrows the picture. This is often faster than reading screenshots from users.

Auditing configuration changes

The same log also records administrative actions, such as someone changing an app integration. If a working login suddenly breaks, a quick look at recent changes to that integration often explains it. Make this the second step of every login incident: ask who changed what, and when.

Metrics worth tracking

Retention and ownership

The System Log keeps events for a limited period, so an investigation that starts weeks after an incident may find nothing. If your organization needs a longer history for compliance or for security reviews, stream or export the log to a long-term store. Also decide who owns the dashboards and alerts. A monitor that nobody reads is no better than having none, so name a team that reviews failures weekly and a person who is paged when failures spike.

Alerting

Consider an alert when failed redirect checks spike for one application, because it usually means a deployment changed the callback address without updating Okta. Also alert on any redirect URI that contains a non-https, non-local address in production integrations, since that is almost always an error.

Good habits keep the configuration small, clear, and safe.

Helpful patterns

Best practices summary

These examples show how the ideas work in typical company situations.

Yes, in practice. Different products and documents use different names, but they all describe the address where results are delivered after login.

Yes. An app integration can hold several. Your app picks one for each request. Keep the list short and make sure each entry has a clear purpose.

For standard behavior, yes. The request must match a registered entry exactly, including scheme, host, port, path, and trailing slash. Any wildcard-style option is an opt-in setting that Okta cautions about, so verify it in current documentation.

Because the server’s address was never registered. Localhost entries and server entries are separate addresses, so each needs its own entry in the right integration.

No. Services that use the client credentials grant do not involve a browser, so there is nothing to redirect.

A redirect URI is a full address inside one app integration, saying where login results may go. A trusted origin is an org-level entry of scheme, host, and port, saying which web pages may call Okta from the browser or receive redirects.

Only for localhost during development. Every other address should use https so the code in the address cannot be observed on the network.

If your app asks Okta to send the user to a page after logout, Okta checks that page against the sign-out list. Without an entry, logout may succeed but the user lands on an error page.

Check that you edited the integration that owns the client ID in the request, that your app points to the intended Okta org and authorization server, and that the change was actually saved. Also check whether the problem is really a trusted origin or an assignment issue.

Each app integration keeps its own list, so two apps can technically list the same address, but doing so usually signals a design problem. Separate applications should have separate callback routes and separate integrations.

No. They solve different problems. Registration controls where results may go. PKCE ensures that only the app that started the login can use the code. You should use both.

Normally within moments of saving, so you can test right away. If a change seems not to apply, reopen the integration and confirm it was saved before looking for other causes.

It is better to use a dedicated callback route. A home page does many other things, such as loading scripts and tracking visits, and you want the page that receives the code to do one job and do it quickly. After the code is exchanged, send the user to the home page or wherever they were headed.

Avoid relying on it. Because matching is strict, extra parameters can cause mismatches that are hard to spot. Keep the registered address simple, and carry any extra information your app needs inside the state value or inside your own session instead.

Redirect URIs themselves do not belong to a person, but the Okta account used to edit them does. Remove or reduce that person’s administrator rights, and review any personal test addresses they added to shared integrations, such as links to their own machines or demo sites.

The idea is similar but the name is different. SAML applications use an assertion consumer service address, which plays the role of the redirect URI by telling Okta where to post the sign-in result. It also needs exact, careful registration, but this guide covers the OpenID Connect and OAuth settings specifically.

A redirect URI is the registered address where Okta delivers the result of a login. Okta insists on registration because whoever receives the authorization code can impersonate the user, and an exact-match allow-list is the simplest dependable defense. Once you understand where the address is checked, which fields exist, how application types differ, and how trusted origins complement redirect URIs, most sign-in problems turn into short, predictable checks rather than long mysteries. Treat your redirect URI lists like any other piece of security configuration: keep them small, explicit, reviewed, and consistent with your application.