Skip to content
Connect2id

Redirection URI template

1. Philosophy of the redirect_uri template

The special redirect_uri template feature of the Connect2id server is intended to help in the following scenarios:

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

  • A client may require a multitude of redirection URIs which individual registration may be impractical.

This feature is introduced in Connect2id server v13.4.

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 which must contain a single [param] placeholder, to be set dynamically by the Connect2id server at the authorisation endpoint when it handles a request. The [param] can appear anywhere in the template URI, or may represent the entire URI.

Example redirect_uri template:

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

The effective redirect_uri after applying a parameter, e.g. iss123:

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

3. Client registration

To register an OAuth 2.0 web or native client with a template for its redirection URI simply include the template URI in the redirect_uris metadata field (a JSON array).

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 in the redirect_uri of 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 will process the template to produce the effective redirection URI, where the authorisation response will be delivered.

Note, in its token request the client must use this effective redirection URI (e.g. https://iss123.example.com/login-callback) and not the template URI.

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

4. How to set the redirect_uri template parameter

The [param] must be set in the authorisation session start object when the Connect2id server deployment has received a new request at its authorisation endpoint. The parameter is passed in the optional redirect_uri_template_param.

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"
}

5. Security

The template parameter must be set by logic controlled by the Connect2id server.

If the [param] doesn’t get set the effective redirect_uri will remain the template URI, which being a URN will cause the redirection to fail.