Configuring Redirect URI Policies

Redirecting is an important security aspect of OAuth flows. In Code Flow, Implicit Flow and Hybrid Flow it gives certainty that tokens and the authorization code (if used) are sent to the right party, assuming that the client has configured a redirect URI they are in control of. This is also why clients need to configure possible redirect URIs in the system, or register them during a Dynamic Client Registration (DCR) request.

To ensure the best security, the redirect URI value passed in an authorization request is matched exactly with the value configured for the client. This however, in some cases, stifles usability. In some scenarios, for example during development, it's faster and easier for the developer to be able to loosen up the strict checks of redirect URIs. Redirect URI validation can also be less strict in flows where the client authenticates before making an authorization request. This is the case of JWT Authorization Requests (JAR) and Pushed Authorization Requests (PAR). During such requests, the Authorization Server has a good certainty of the authenticity of the client, thus it may accept variations of the redirect URI. This can be useful in setups where one client operates on different, dynamic subdomains, or where dynamic query parameters are used in the redirect URI.

Redirect URI Policies in the Curity Identity Server

Since version 6.7. of the Curity Identity Server administrators can set up policies used for redirect URI request validation. An OAuth profile can have numerous policies configured, and one is always marked as the default. The default policy is used during authorization requests, unless the client has a different policy assigned.

Configuring Redirect URI Policies

In the admin UI go to an OAuth Profile -> General, then scroll to the Redirect URI Policies section.

Click on the toggle to enable using Redirect URI Policies for the profile. You will see a note about the deprecated settings. Click on the + New Policy button to add a new policy and enter a name.

You can now define the policy parameters. These are divided into three parts:

• Policy parameters applicable to all authorization requests.
• Policy parameters applicable to authorized requests (PAR and JAR).
• Policy parameters applicable to DCR requests.

Parameters Applicable to All Authorization Requests

The following parameters will affect all authorization requests.

1. Allow Localhost Variations. This setting is particularly useful in development environments. When enabled, then a client with a registered localhost redirect URI can use any redirect URI which uses a loopback interface. The scheme, port, path and query string of the redirect URI do not have to match the registered value. For example, for a registered URI value of http://localhost, any of the following can be used as the redirect_uri parameter value:

   • http://localhost
   • http://127.0.0.1:8080
   • https://localhost:8000/callback

2. Allow Query String Variations. Enabling this setting allows clients to use query string parameters other than those configured in the client's redirect URI. For example, for a registered URI value of http://example.com:8080/callback, you could use these redirect URIs:

   • http://example.com:8080/callback?param=123
   • http://example.com:8080/callback?param1=a&param2=b

but not https://example.com:8080/callback?param=123 (different scheme) or http://example.com:8181/callback?param=123 (different port).

Parameters Applicable to PAR and JAR

The following settings are taken into consideration only when the client performs an authenticated authorization request, i.e. uses PAR or JAR.

1. Validate Port. When disabled, then redirect URIs in the authorization request can use any port. For example, for a registered URI value of http://example.com:8080/callback, you could use these redirect URIs: http://example.com:3000/callback, http://example.com/callback, etc. This setting proves particularly useful for native apps, which obtain an available ephemeral port from the operating system only when performing a request.

2. Validate Path. When disabled, then redirect URIs in the authorization request can use any path. For example, for a registered URI value of http://example.com:8080/callback, you could use these redirect URIs: http://example.com:8080/another-callback, http://example.com:8080/, etc.

3. Allow Suffix Path. When enabled, then redirect URIs in the authorization request can have suffixes added to the path segment. For example, for a registered URI value of http://example.com:8080/callback, you could use these redirect URIs: http://example.com:8080/callback/another, http://example.com:8080/callback2, etc.

4. Validate Query String. When disabled, then redirect URIs in the authorization request can use any query string parameters. When enabled then dynamic clients must match the query string. Static clients must use a redirect URI which starts with the query string from the configuration. For example, for a registered URI value of http://example.com:8080/callback?param=abc, you could use these redirect URIs:

   • when disabled: http://example.com:8080/callback?other-param=123, http://example.com:8080/callback?param=def&other-param=123, etc.
   • when enabled, for a static client: http://example.com:8080/callback?param=abc&other-param=123, etc.
   • when enabled, for a dynamic client, only exact match can be used, i.e. http://example.com:8080/callback?param=abc.

5. Domain Validation. Defines how the domain of the redirect URI in the authorization request can differ from the configured domain:

   • exact. Only exactly same domains can be used.
   • no-validation. The domain can differ completely, e.g. http://other-example.co.uk:8080/callback can be used when http://example.com:8080/callback is registered.
   • tld-plus-one. The two right-most segments of the domain must match the registered value. For example, for a registered URI value of http://example.com/callback, you could use these redirect URIs: http://test.example.com/callback, http://api.example.com/callback, but not http://test.com/callback.
   • tld-plus-two. The three right-most segments of the domain must match the registered value. For example, for a registered URI value of http://example.co.uk/callback, you could use these redirect URIs: http://test.example.co.uk/callback, http://api.example.co.uk/callback, but not http://test.co.uk/callback

Parameters Applicable to Client Registration

The parameters in this section can be used to loosen the restrictions of redirect URIs registered during Dynamic Client Registration requests.

1. Allow HTTP. When enabled, then clients can use non-TLS redirect URIs when registering (URIs with the http scheme).

Enforcing the Policy

All clients configured in the given OAuth profile will have the default policy applied when making authorization requests. The default policy is set with the Default Policy toggle on the list of Redirect URI Policies.

Clients can have their own Redirect URI Policies assigned. When a client has a policy assigned, then it overrides all settings from the default policy. To assign a Redirect URI Policy to a client, go to Token Service -> Clients and edit a chosen client, then go to the Client Application Settings section. Choose a policy from the dropdown menu for the Redirect URI Validation Policy option.

Conclusion

Redirect URI Policies allow clients to use different redirect URIs during authorization requests than the ones configured for the given client. Enabling this can be useful in numerous solutions — for example to ease development, to be used in multi-tenant scenarios, or by native apps which might operate on dynamic ports.