OAuth 2.0 / OpenID Connect client registration endpoint

1. Clients must be registered

Client applications must be registered with the Connect2id server before they can login end-users with OpenID Connect or request OAuth 2.0 access tokens.

Client registration is specified in:

• OpenID Connect Dynamic Client Registration 1.0 – for OpenID Connect relying parties that require an ID token user sign-in.

• OAuth 2.0 Dynamic Client Registration Protocol - RFC 7591 – for OAuth 2.0 clients that require only authorisation and no ID token, such as clients using the client credentials grant.

• OAuth 2.0 Dynamic Client Registration Management Protocol - RFC 7592 – describes how to read, update or delete a client registration.

2. The client registration endpoint URL

It is advertised in the registration_endpoint server metadata and has this form:

[issuer-url]/clients

3. Accessing the client registration endpoint

The client registration endpoint supports two modes, controlled by the allow-open-registration configuration setting:

• Open registration — Clients can be registered without an initial access token for the authorization_code, implicit and refresh_token grants. This mode is intended for publicly available Connect2id servers configured for automatic OpenID Provider discovery. An initial access token is required to register clients for other grants or to set privileged registration parameters, as described below.

• Managed registration — An initial access token is required to register any client. Registration can be managed through an admin or developer portal, or another pre-authorisation process, such as software statements (requires a plugin).

3.1 Initial access token

The Connect2id server accepts two types of initial access token:

• The configured master token, which provides unrestricted access to the client registry.

• An access token issued by the Connect2id server, valid for a single registration. Its scope determines which grant types and privileged registration parameters the registrant can set:

  • client-reg — Permits registration with any grant_types values and unrestricted use of the privileged parameters listed below. This scope provides permissions equivalent to the master token for registering a client. Use it with caution; it may be discontinued in a future release for safety reasons.
  • client-reg:grant:code — Permits the authorization_code grant type.
  • client-reg:grant:implicit — Permits the implicit grant type.
  • client-reg:grant:refresh — Permits the refresh_token grant type.
  • client-reg:grant:password — Permits the password grant type.
  • client-reg:grant:client — Permits the client_credentials grant type.
  • client-reg:grant:jwt — Permits the urn:ietf:params:oauth:grant-type:jwt-bearer grant type.
  • client-reg:grant:saml — Permits the urn:ietf:params:oauth:grant-type:saml2-bearer grant type.
  • client-reg:grant:token_exchange — Permits the urn:ietf:params:oauth:grant-type:token_exchange grant type.
  • client-reg:grant:ciba — Permits the urn:openid:params:grant-type:ciba grant type.
  • client-reg:scope — Permits setting the scope registration parameter. To restrict the permitted scope values, append each value to client-reg:scope:, as shown in the example below.
  • client-reg:data — Permits setting the custom data registration parameter, which stores arbitrary JSON object data for the client.
  • client-reg:set-id — Permits specifying the client identifier in the custom preferred_client_id metadata parameter.
  • client-reg:set-secret — Permits specifying the client secret in the custom preferred_client_secret metadata parameter.
  • client-reg:set-sector-id-urn — Permits setting the sector_identifier_uri metadata parameter to a URN identifying a sector managed by the OpenID provider.

Example scope granting unrestricted registration permissions:

client-reg

Example scope permitting only the authorization_code and refresh-token grants:

client-reg:grant:code client-reg:grant:refresh_token

Example scope permitting the password grant and allowing the registrant to set the client’s scope parameter to openid, email or both:

client-reg:grant:password client-reg:scope:openid client-reg:scope:email

An initial access token can be obtained from the Connect2id direct authorisation endpoint.

Pass the initial access token in the registration request’s Authorization header using the Bearer scheme:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

3.2 Registration access token

Upon successful registration the client is issued a registration access token. This access token can be used by the client to self-manage its registration in a RESTful manner: read, modify or delete it.

4. Web API overview

5. Resources

5.1 /clients

5.1.1 POST

Registers a new OAuth 2.0 client / OpenID relying party.

Header parameters:

• [ Authorization ] Required if open registration is disabled, or if an initial access token is needed.

• Content-Type Must be set to application/json.

• [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

• [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Query parameters:

• [ dry_run = false ] {true|false} When true the new client is not stored in the database. Intended for testing purposes. Since 19.1.

Body:

• A JSON object representation of the client metadata.

Success:

• Code: 200

• Content-Type: application/json

• Body: {object} The client information response.

Errors:

• 400 Bad Request
• 401 Unauthorized
• 500 Internal Server Error

Example client registration request:

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

{
  "application_type"                : "web",
  "redirect_uris"                   : [ "https://client.example.org/callback",
                                        "https://client.example.org/callback2" ],
  "client_name"                     : "My Cool App",
  "logo_uri"                        : "https://client.example.org/logo.png",
  "token_endpoint_auth_method"      : "client_secret_basic",
  "contacts"                        : [ "[email protected]" ]
}

Example client registration response detailing the provisioned identifier, secret, registration access token and metadata:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "client_id"                       : "s6BhdRkqt3",
  "client_secret"                   : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
  "client_secret_expires_at"        : 1577858400,
  "registration_access_token"       : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
  "registration_client_uri"         : "https://c2id.com/clients/s6BhdRkqt3",
  "client_name"                     : "My Cool App",
  "logo_uri"                        : "https://client.example.org/logo.png",
  "contacts"                        : [ "[email protected]" ],
  "application_type"                : "web",
  "grant_types"                     : [ "authorization_code",
                                        "refresh_token" ],
  "response_types"                  : [ "code" ],
  "redirect_uris"                   : [ "https://client.example.org/callback",
                                        "https://client.example.org/callback2" ],
  "token_endpoint_auth_method"      : "client_secret_basic",
  "id_token_signed_response_alg"    : "RS256",
  "subject_type"                    : "public"
}

5.1.2 GET

Retrieves the registered OAuth 2.0 clients / OpenID relying parties. In Connect2id server deployments with very large numbers of clients this can be a potentially expensive operation and should be used with care.

Header parameters:

• [ Authorization ] The configured master access token for the client registry.

• [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

• [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Success:

• Code: 200

• Content-Type: application/json

• Body: {array} JSON array of the registered clients, empty array if none.

Errors:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 500 Internal Server Error

Example request to get the registered clients:

GET /clients HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response listing two clients:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

[
  {
    "client_id"                       : "s6BhdRkqt3",
    "client_secret"                   : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
    "client_secret_expires_at"        : 1577858400,
    "registration_access_token"       : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
    "registration_client_uri"         : "https://c2id.com/clients/s6BhdRkqt3",
    "client_name"                     : "My Cool App",
    "logo_uri"                        : "https://client.example.org/logo.png",
    "contacts"                        : [ "[email protected]" ],
    "application_type"                : "web",
   "grant_types"                      : [ "authorization_code",
                                          "refresh_token" ],
    "response_types"                  : [ "code" ],
    "redirect_uris"                   : [ "https://client.example.org/callback",
                                          "https://client.example.org/callback2" ],
    "token_endpoint_auth_method"      : "client_secret_basic",
    "id_token_signed_response_alg"    : "RS256",
    "subject_type"                    : "public"
  },

  {
    "client_id"                       : "joaix93Kf4",
    "client_secret"                   : "posIjfdOJlejLfdsP0dfk23xkKJwpKfjLkdlslsOz",
    "client_secret_expires_at"        : 1577858400,
    "registration_access_token"       : "POifsadPOIe30xcPJeOjfo2zp_dfsdfoifas_3234",
    "registration_client_uri"         : "https://c2id.com/clients/joaix93Kf4",
    "client_name"                     : "My Test App",
    "logo_uri"                        : "https://app.example.org/logo.png",
    "contacts"                        : [ "[email protected]" ],
    "application_type"                : "web",
    "grant_types"                     : [ "authorization_code",
                                          "refresh_token" ],
    "response_types"                  : [ "code" ],
    "redirect_uris"                   : [ "https://app.example.org/callback" ],
    "token_endpoint_auth_method"      : "client_secret_basic",
    "id_token_signed_response_alg"    : "RS256",
    "subject_type"                    : "public"
  }
]

5.2 /clients/{id}

5.2.1 GET

Retrieves an OAuth 2.0 client / OpenID relying party. The Connect2id server will automatically provision a new client secret if the previous one has expired.

Note, if the client identifier is invalid, the Connect2id server will return a 401 Unauthorized status, as mandated by RFC 7592 for security reasons; privileged requests with the master bearer access token will return 404 Not Found.

Path parameters:

• id {string} The client identifier.

Header parameters:

• Authorization Must specify the configured master bearer access token or the provisioned registration access token.

• [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

• [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Success:

• Code: 200

• Content-Type: application/json

• Body: {object} The client information response.

Errors:

• 400 Bad Request
• 401 Unauthorized
• 404 Not Found
• 500 Internal Server Error

Example request to retrieve of the registration of client with ID s6BhdRkqt3:

GET /clients/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0

Example response detailing the registered client information:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "client_id"                       : "s6BhdRkqt3",
  "client_secret"                   : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
  "client_secret_expires_at"        : 1577858400,
  "registration_access_token"       : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
  "registration_client_uri"         : "https://c2id.com/clients/s6BhdRkqt3",
  "client_name"                     : "My Cool App",
  "logo_uri"                        : "https://client.example.org/logo.png",
  "contacts"                        : [ "[email protected]" ],
  "application_type"                : "web",
  "grant_types"                     : [ "authorization_code",
                                        "refresh_token" ],
  "response_types"                  : [ "code" ],
  "redirect_uris"                   : [ "https://client.example.org/callback",
                                        "https://client.example.org/callback2" ],
  "token_endpoint_auth_method"      : "client_secret_basic",
  "id_token_signed_response_alg"    : "RS256",
  "subject_type"                    : "public"
}

5.2.2 PUT

Modifies an OAuth 2.0 client / OpenID relying party registration.

The Connect2id server will update the registration access token for the client and if configured or supplied with a preferred_client_secret its secret as well. If the client secret is updated, the previous remains valid for another 30 minutes for a seamless rollover.

Note, if the client identifier is invalid, the Connect2id server will return a 401 Unauthorized status, as mandated by RFC 7592 for security reasons; privileged requests with the master bearer access token will return 404 Not Found.

Path parameters:

• id {string} The client identifier.

Header parameters:

• Authorization Must specify the configured master bearer access token or the provisioned registration access token.

• Content-Type Must be set to application/json.

• [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

• [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Query parameters:

• [ dry_run = false ] {true|false} When true the modification is not stored in the database. Intended for testing purposes. Since 19.1.

Body:

• A JSON object representation of the client metadata.

Success:

• Code: 200

• Content-Type: application/json

• Body: {object} The client information response.

Errors:

• 400 Bad Request
• 401 Unauthorized
• 404 Not Found
• 500 Internal Server Error

Example client update request:

PUT /clients/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0
Content-Type: application/json

{
  "client_id"                  : "s6BhdRkqt3",
  "application_type"           : "web",
  "redirect_uris"              : [ "https://client.example.org/callback",
                                   "https://client.example.org/callback2" ],
  "client_name"                : "My Cool App",
  "logo_uri"                   : "https://client.example.org/logo.png",
  "policy_uri"                 : "https://client.example.org/privacy-policy",
  "tos_uri"                    : "https://client.example.org/terms-of-service",
  "token_endpoint_auth_method" : "client_secret_basic",
  "contacts"                   : [ "[email protected]" ]
}

Example client update response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "client_id"                    : "s6BhdRkqt3",
  "client_secret"                : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
  "client_secret_expires_at"     : 1577858400,
  "registration_access_token"    : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
  "registration_client_uri"      : "https://c2id.com/clients/s6BhdRkqt3",
  "client_name"                  : "My Cool App",
  "logo_uri"                     : "https://client.example.org/logo.png",
  "policy_uri"                   : "https://client.example.org/privacy-policy",
  "tos_uri"                      : "https://client.example.org/terms-of-service",
  "contacts"                     : [ "[email protected]" ],
  "application_type"             : "web",
  "grant_types"                  : [ "authorization_code",
                                     "refresh_token" ],
  "response_types"               : [ "code" ],
  "redirect_uris"                : [ "https://client.example.org/callback",
                                     "https://client.example.org/callback2" ],
  "token_endpoint_auth_method"   : "client_secret_basic",
  "id_token_signed_response_alg" : "RS256",
  "subject_type"                 : "public"
}

5.2.3 DELETE

Deletes an OAuth 2.0 client / OpenID relying party registration.

As part of the delete request, any active refresh and access tokens as well as any existing long-lived (persisted) authorisations for the client are revoked (synchronously). If the client has long-lived authorisations from many subjects, their removal can be a potentially expensive operation.

If the client identifier is invalid, the Connect2id server returns a 401 Unauthorized status, as mandated by RFC 7592 for security reasons; privileged requests with the master access token return a 404 Not Found instead.

Path parameters:

• id {string} The client identifier.

Header parameters:

• Authorization Must specify the configured master bearer access token or the provisioned registration access token.

• [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

• [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Success:

• Code: 204

Errors:

• 400 Bad Request
• 401 Unauthorized
• 404 Not Found
• 500 Internal Server Error

Example request to delete the registration of client with ID s6BhdRkqt3:

DELETE /clients/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0

Example response indicating successful deletion:

HTTP/1.1 204 No Content

6. Representations

6.1 Client metadata

OpenID Connect client metadata, as specified in OpenID Connect Dynamic Client Registration 1.0, section 2.

For simple OAuth 2.0 clients that don’t require OpenID Connect, e.g. clients using the client credentials grant - OAuth 2.0 client metadata, as specified in the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), section 2.

Note, the scope parameter, intended to set the allowed scope values for a client, is supported for OAuth 2.0 client as well as OpenID Connect registrations.

Client metadata parameters from the following OAuth 2.0 and OpenID Connect extensions are also supported:

• Mutual TLS client certificate bound access tokens (mTLS)
• OAuth 2.0 Demonstrating Proof of Possession (DPoP)
• Pushed authorisation requests (PAR)
• JWT-secured authorisation responses (JARM)
• OpenID Connect RP-Initiated Logout 1.0
• OpenID Connect Front-Channel Logout 1.0
• OpenID Connect Back-Channel Logout 1.0
• OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0 (CIBA)
• OpenID Connect for Identity Assurance 1.0
• OpenID Federation 1.0

In addition to the standard client metadata parameters, the Connect2id server supports the following optional custom parameters:

• [ redirect_uris ] {string array} Supports registration of one or more redirection URI templates.

• [ code_challenge_method ] {string} Sets a code challenge method (RFC 7636) the client must use. Supported values are S256 and plain. The default value is none. Since v13.0.

• [ data ] {object} Optional custom data, as a JSON object.

• [ preferred_client_id ] {string} Sets the client_id for a new client instead of letting the Connect2id server generate an identifier. Can be used to import a client registration from another server.

• [ preferred_client_secret ] {string} Sets the client_secret for a new client or in a client update. Can be used to import a client registration from another server.

• [ refresh_client_secret = false] {true|false} If true triggers a generation of a new client_secret when updating a client, regardless of the expiration status of the current client secret and the configured op.reg.alwaysRefreshClientSecretOnUpdate policy. A preferred_client_secret overrides the action of this field. The default value is false (no new secret generation).

• [ sector_identifier_uri ] {string} The standard OpenID Connect parameter for specifying a sector identifier URI for the relying party can also be a URN for a sector ID that is managed locally by the OpenID provider. The expected URN format is urn:c2id:sector_id:<id>. The OpenID provider must manage the assignment of the URN sector IDs to relying parties prior to registration and ensure that the ID stays unique for a given OpenID relying party, unless the sector ID is allowed to be shared by two more relying parties, typically when those are under single administrative control. To register URN sector IDs the op.reg.enableProviderManagedSectorIDs configuration property must be enabled.

Concrete examples can be found in the client registration guide.

6.2 Client information

Client information response. Consists of the following JSON object members as well as the JSON object members for the provisioned client metadata.

JSON object members:

• client_id {string} The provisioned unique client identifier. It is represented by a secure random alphanumeric string of the configured length.

• [ client_secret ] {string} The client secret, used by confidential clients to authenticate to the Token Endpoint, as described in the OAuth 2.0 specification. It is represented by a secure random alphanumeric string of the configured length. Omitted for public clients. Also omitted for a GET request when the secret is stored in a hashed form.

  After a client secret update the previous value will remain valid for client authentication purposes for another 30 minutes, to enable a seamless rollover.

• [ encoded_client_secret ] {string} The encoded (hashed) client secret, when provided by a client secret codec plugin. Since v13.5.

• registration_access_token {string} Registration access token that can be used to query, modify or delete the client’s registration. It is represented by a secure random alphanumeric string of the configured length.

• registration_client_uri {string} The URI of the client’s registration. It is formed by appending the client_id to the client registration endpoint path.

• client_id_issued_at {integer} The client identifier issue timestamp, as number of seconds since the Unix epoch.

• [ client_secret_expires_at ] {integer} Time at which the client_secret will expire or 0 if it will not expire, according to the configured client secret lifetime. Its value is represented as number of seconds since the Unix epoch. Omitted for public clients.

7. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON"
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token. Also used to indicate that the client resource (registration URI) doesn’t exist on the server.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

403 Forbidden

The request was denied due to the bearer access token having insufficient privileges.

Example:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope" error_description="Bearer access token has insufficient privileges"

404 Not Found

The requested resource does not exist.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

An unexpected internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error