Skip to content
Connect2id

How to use a redirection URI template for an OAuth 2.0 client

1. Purpose of the redirect_uri template

The special redirect_uri template feature of the Connect2id server is intended for OAuth 2.0 clients where:

  • The exact redirection URI is not known at the time of client registration.

  • The client requires a large number of redirection URIs, making individual registration impractical.

2. The redirect_uri template format

The template is a URN with this format:

urn:c2id:redirect_uri_template:[URI]

The URI is the final redirection URI template. It must contain exactly one [param] placeholder, which is later replaced by the Connect2id server when processing the authorisation request. The [param] placeholder can appear anywhere in the template URI, or it can represent the entire URI.

Example redirect_uri template:

urn:c2id:redirect_uri_template:https://[param].example.com/login-callback

Effective redirect_uri after applying the parameter iss123:

https://iss123.example.com/login-callback

3. Client registration

To register an OAuth 2.0 web or native client with a redirection URI template, include the template URI in the redirect_uris metadata field.

Example client registration request:

POST /clients HTTP/1.1
Host: demo.c2id.com
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris" : [ "urn:c2id:redirect_uri_template:https://[param].example.com/login-callback" ]
}

If the template is missing the [param] placeholder, the Connect2id server will return a client registration invalid_redirect_uri error with a descriptive message.

4. Client-side use of the redirect_uri template

The client must pass the registered template URI as the redirect_uri value in its authorisation requests.

Example request using the code flow:

https://c2id.com/login?
 response_type=code
 &scope=openid
 &client_id=123
 &state=af0ifjsldkj
 &redirect_uri=urn%3Ac2id%3Aredirect_uri_template%3Ahttps%3A%2F%2F%5Bparam%5D.example.com%2Flogin-callback

At the authorisation endpoint the Connect2id server processes the template to produce the effective redirection URI, where the authorisation response will be delivered.

In the subsequent token request, the client must use the effective redirection URI, for example:

https://iss123.example.com/login-callback

The client must not use the template URI in the token request.

JWT secured authorisation requests (JAR) and pushed authorisation requests (PAR) can also use redirection URI templates.

5. How to set the redirect_uri template parameter

The [param] value must be set in the authorisation session start object when the Connect2id server deployment receives a new request at its authorisation endpoint.

The parameter is passed in the optional redirect_uri_template_param field.

Example:

POST /authz-sessions/rest/v3/ HTTP/1.1
Host: demo.c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "query"                       : "response_type=code&scope=openid&client_id=123&state=af0ifjsldkj&redirect_uri=urn%3Ac2id%3Aredirect_uri_template%3Ahttps%3A%2F%2F%5Bparam%5D.example.com%2Flogin-callback",
  "redirect_uri_template_param" : "iss123"
}

6. Security

The template parameter must be determined by server-side logic controlled by the Connect2id server deployment. It must not be copied directly from an untrusted request parameter.

Deployments should validate the parameter before setting it, for example by allowing only expected characters, length and values. This is especially important when the parameter becomes part of the host name or path of the effective redirection URI.

If the [param] value is not set, the effective redirect_uri will remain the template URI. Because the template URI is a URN, the redirection will fail.