Client registration

1. Clients must be registered

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

Client registration is specified in:

OpenID Connect Dynamic Client Registration 1.0 – for OpenID Connect clients. This spec should be used for almost all cases when you need to register an application with the Connect2id server.
OAuth 2.0 Dynamic Client Registration Protocol - RFC 7591 – for simple OAuth 2.0 clients that don’t need OpenID Connect features, e.g. 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

The client registration endpoint URL can be found out from the server metadata endpoint and looks like this:

https://[base-server-url]/clients

3. Accessing the client registration endpoint

The client registration endpoint operates in an open or managed mode, depending on the allow-open-registration configuration setting:

Open registration – Client applications can be freely registered for the commonly used authorization, implicit and refresh_token grants. Open registration is intended for publicly available Connect2id servers configured for automatic OpenID Provider discovery. Note that open registration is limited to the above grants only; an initial access token is required to register a client for other grants, such as password, or to set privileged registration parameters (see next section).
Managed registration – All registration is managed, by an admin or developer portal, or by some other pre-authorisation process, such as software statements. An initial access token (of type OAuth 2.0 bearer), described in the next section, is required to register a new client.

3.1 Initial access token

The Connect2id server accepts two types of access tokens to register a new client:

The configured master token for unrestricted access to the client registry.
An access token issued by the Connect2id server, valid for a single registration only, and having one or more of the following scope values:
- client-reg – Permits registration of a client with any grant_types values and the scope parameter set (equivalent to the master access token, or all of the scope values below).
- client-reg:grant:code – Permits registration of a client with an authorization_code grant type.
- client-reg:grant:implicit – Permits registration of a client with an implicit grant type.
- client-reg:grant:refresh – Permits registration of a client with a refresh_token type.
- client-reg:grant:password – Permits registration of a client with a password grant type.
- client-reg:grant:client – Permits registration of a client with a client_credentials grant type.
- client-reg:grant:jwt – Permits registration of a client with a urn:ietf:params:oauth:grant-type:jwt-bearer grant type.
- client-reg:grant:saml – Permits registration of a client with a urn:ietf:params:oauth:grant-type:saml2-bearer grant type.
- client-reg:scope – Permits setting of the scope registration parameter, which may have special meaning for password and other grant handlers. You may append a text string to it to lock down the allowed scope values that the registrant may set. See the example below.
- client-reg:data – Permits setting of the custom data registration parameter which may be used to store arbitrary JSON object data for the client.
- client-reg:set-id – Permits registration of a client with an identifier specified in a custom preferred_client_id client metadata parameter.
- client-reg:set-secret – Permits registration of a client with an secret specified in a custom preferred_client_secret client metadata parameter.

Example scope permitting registration of any grant types:

client-reg

Example scope permitting registration of a client for the authorization_code and implicit grants only:

client-reg:grant:code client-reg:grant:implicit

Example scope to permit registration of a client for the password grant and also allow the registrant to set the openid and email client scopes:

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

An initial access token can be obtained by making a request to the Connect2id direct authorisation endpoint.

The initial acess token must be passed with the HTTP request in the Authorization header:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

3.2 Registration access token

Upon successful registration the client application is issued a registration access token. This access token can be used to query, modify or delete the client’s registration in a RESTful manner.

4. Web API overview

Resources
/clients [POST] [GET] /clients/{id} [GET] [PUT] [DELETE]
Representations	Errors
Client metadata Client information	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

5. Resources

5.1 /clients

5.1.1 POST

Registers a new OAuth 2.0 / OpenID Connect client.

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.

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"                        : [ "admin@example.org" ]
}

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"                        : [ "admin@example.org" ],
  "application_type"                : "web",
  "grant_types"                     : [ "authorization_code" ],
  "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 / OpenID Connect clients. For Connect2id servers 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.

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"                        : [ "admin@example.org" ],
    "application_type"                : "web",
    "grant_types"                     : [ "authorization_code" ],
    "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"                        : [ "admin@example.org" ],
    "application_type"                : "web",
    "grant_types"                     : [ "authorization_code" ],
    "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 / OpenID Connect client registration. The Connect2id server will return a new client secret if the previous one has expired.

Note that 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 which use 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.

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"                        : [ "admin@example.org" ],
  "application_type"                : "web",
  "grant_types"                     : [ "authorization_code" ],
  "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 / OpenID Connect client registration. The Connect2id server will provision a new registration access token and client secret.

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.

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"                   : [ "admin@example.org" ]
}

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"                     : [ "admin@example.org" ],
  "application_type"             : "web",
  "grant_types"                  : [ "authorization_code" ],
  "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 / OpenID Connect client registration. All refresh tokens, access tokens and long-lived authorisations (sticky grants) for the client will be revoked / deleted too.

Path parameters:

id {string} The client identifier.

Header parameters:

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

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 the OpenID Connect features, 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.

Additionally to the standard OpenID and OAuth client metadata parameters, the Connect2id server also supports the following optional parameters:

[ data ] {object} Optional custom data, in the form of a JSON object.
[ preferred_client_id ] {string} Presets the identifier for a new client. Used to import a client registration from another server.
[ preferred_client_secret ] {string} Presets the secret for a new client. Used to to import a client registration from another server.

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.
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: Unexpected token foo at position 3."
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token. Also used to indicate that the client (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 doesn’t exist.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

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

Example:

HTTP/1.1 500 Internal Server Error