HTTP redirection configuration

Self-Service flows such as Login, Registration, Updating Settings support two successful response modes:

• For browsers, the response will be a redirection.
• For API clients (this includes AJAX) the response will be in JSON.

Redirection

Browser requests, identified by the Accept: text/html header, complete with a redirection flow. If no redirection URL is set for the flow, the Default Redirect URL will be used for most flows (for example login, registration):

selfservice:
  default_browser_return_url: https://always-end-up-here-per-default/

It's possible to specify a redirect URL per Self-Service Flow:

selfservice:
  flows:
    login:
      after:
        default_browser_return_url: https://end-up-here-after-login/
    registration:
      after:
        default_browser_return_url: https://end-up-here-after-registration/
    # verification
    # ...

You may also set redirect URLs per method (overrides selfservice.flows.<login|registration|...>.default_return_to):

selfservice:
  flows:
    login:
      after:
        default_browser_return_url: https://this-is-overridden-by-password/
        password:
          default_browser_return_url: https://end-up-here-after-login-with-password/
      # ...

It's also possible to redirect someone back to the original URL. For example, if a user requests https://www.myapp.com/blog/write but isn't logged in, we want the user to end up at that page after login. To achieve that, you append ?return_to=https://www.myapp.com/blog/write when initializing the Login / Registration /Settings flow.

Because Ory Identities prevents Open Redirect Attacks, you need to whitelist the domain in your Ory Identities config when using the ?return_to= query parameter. For other return urls specified inside the configuration it isn't necessary to add the domain to the whitelist.

Let's look at an example, here we're adding myapp.com to the whitelist, thus we can now specify a dynamic return url like so ?return_to=https://www.myapp.com/blog/write.

selfservice:
  allowed_return_urls:
    - https://www.myapp.com/

Ory Kratos Identities compares the path of an allowed_return_urls entry segment by segment. An entry allows its own path and every path below it, but not a path that only starts with the same characters:

selfservice:
  allowed_return_urls:
    # Allows https://www.myapp.com/app and https://www.myapp.com/app/settings,
    # but not https://www.myapp.com/application.
    - https://www.myapp.com/app
    # Add a path that only shares a prefix with another entry as its own entry.
    - https://www.myapp.com/application

A trailing slash doesn't change the match: https://www.myapp.com/app/ allows the same URLs as https://www.myapp.com/app.

Ory Kratos Identities resolves . and .. segments in the return_to path before it compares, including percent-encoded ones such as %2e%2e. A return_to URL is rejected when its path resolves outside the entry, for example https://www.myapp.com/app/../admin. A percent-encoded slash (%2F) doesn't separate segments, so https://www.myapp.com/app%2Fsettings doesn't match https://www.myapp.com/app.

Post-login redirection

Post-login redirection considers the following configuration keys:

selfservice:
  default_browser_return_url: https://end-up-here-per-default/
  flows:
    login:
      after:
        # overrides url.default_browser_return_url
        default_browser_return_url: https://this-is-overridden-by-password/
        password:
          # overrides selfservice.login.after.default_browser_return_url
          default_browser_return_url: https://end-up-here-after-login-with-password/

Post-registration redirection

Post-registration redirection considers the following configuration keys:

selfservice:
  default_browser_return_url: https://end-up-here-per-default/
  flows:
    registration:
      after:
        # overrides url.default_browser_return_url
        default_browser_return_url: https://this-is-overridden-by-password/
        password:
          # overrides selfservice.registration.after.default_browser_return_url
          default_browser_return_url: https://end-up-here-after-registration-with-password/

Post-settings redirection

Post-settings redirection doesn't use the urls.default_redirect_to configuration key. Instead the redirect ends at the same Settings UI with the same Settings Request ID and key state set to success. If the listed keys are set, the redirection will end up at the specified values:

selfservice:
  flows:
    settings:
      after:
        default_redirect_to: https://this-is-overridden-by-password/
        password:
          # overrides selfservice.settings.after.default_redirect_to
          default_redirect_to: https://end-up-here-after-settings-with-password/

Post-verification redirection

Post-verification redirection doesn't use the urls.default_redirect_to configuration key. Instead the redirect ends at the same Verification UI with the same Verification Request ID and key state set to passed_challenge. If the listed keys are set, the redirection will end up at the specified values:

selfservice:
  flows:
    verification:
      after:
        default_redirect_to: https://this-is-overridden-by-password/

Specify redirection URL during registration

Verification emails are usually sent in response to a successful registration flow. To specify the redirect URL for the verification flow after registration, append after_verification_return_to to the Browser Registration Init endpoint:

https://public.url/self-service/registration/browser?after_verification_return_to=https://my-redirect/foo

JSON

Requests from API clients - for example AJAX - are identified by the Accept: application/json header and return a JSON response. If no redirection URL is set for the flow, the default_redirect_to URL will be used for most flows.