Products » Connect2id server » Documentation » Old versions » Connect2id server 2.x » Standard endpoints »

OAuth 2.0 / OpenID Connect client registration endpoint

1. Introduction

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 the following documents:

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 - draft-ietf-oauth-dyn-reg-17 -- for simple OAuth 2.0 clients that don't need the OpenID Connect features, e.g. clients using the client credentials grant.
OAuth 2.0 Dynamic Client Registration Management Protocol - draft-ietf-oauth-dyn-reg-management-01 -- describes how to read, update or delete an existing client registration.

2. 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 enabled -- Client applications can be freely registered for the most 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 acces token is still required to register a client for the special password and client_credentials grants, as well as to set the scope registration parameter (see below).
Open registration disabled -- This implies that all registration is managed, by an admin or developer portal, or some other pre-authorisation process. An initial access token (of type OAuth 2.0 bearer), described in the next section, is required to register a new client.

2.1 Initial access token

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

The configured master access token for the client registry. It permits setting of any grant_types values and the scope parameter.
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:scope -- Permits setting of the scope registration parameter, which may have special meaning for password and client_credentials grant handlers.
- 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

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

2.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.

3. Web API overview

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

4. Resources

4.1 /client-reg

4.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 /client-reg 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/client-reg/s6BhdRkqt3",
 "client_name"                     : "My Cool App",
 "logo_uri"                        : "https://client.example.org/logo.png",
 "contacts"                        : [ "[email protected]" ],
 "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"
}

4.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 /client-reg 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/client-reg/s6BhdRkqt3",
   "client_name"                     : "My Cool App",
   "logo_uri"                        : "https://client.example.org/logo.png",
   "contacts"                        : [ "[email protected]" ],
   "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/client-reg/joaix93Kf4",
   "client_name"                     : "My Test App",
   "logo_uri"                        : "https://app.example.org/logo.png",
   "contacts"                        : [ "[email protected]" ],
   "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"
  }
]

4.2 /client-reg/{id}

4.2.1 GET

Retrieves an existing OAuth 2.0 / OpenID Connect client registration. The Connect2id server will returned a new client secret if the previous one has expired.

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
500 Internal Server Error

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

GET /client-reg/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/client-reg/s6BhdRkqt3",
 "client_name"                     : "My Cool App",
 "logo_uri"                        : "https://client.example.org/logo.png",
 "contacts"                        : [ "[email protected]" ],
 "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"
}

4.2.2 PUT

Modifies an existing 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
500 Internal Server Error

Example client update request:

PUT /client-reg/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0
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",
 "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/client-reg/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" ],
 "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"
}

4.2.3 DELETE

Deletes an existing OAuth 2.0 / OpenID Connect client registration.

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
500 Internal Server Error

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

DELETE /client-reg/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0

Example response indicating successful deletion:

HTTP/1.1 204 No Content

5. Representations

5.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 OAuth 2.0 Dynamic Client Registration Protocol (draft-ietf-oauth-dyn-reg-20), section 2.

5.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.
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.

6. 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

OAuth 2.0 / OpenID Connect client registration endpoint

1. Introduction

2. Accessing the client registration endpoint

2.1 Initial access token

2.2 Registration access token

3. Web API overview

4. Resources

4.1 /client-reg

4.1.1 POST

4.1.2 GET

4.2 /client-reg/{id}

4.2.1 GET

4.2.2 PUT

4.2.3 DELETE

5. Representations

5.1 Client metadata

5.2 Client information

6. Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Connect2id server

Documentation

Contact

PRODUCTS

OPEN SOURCE

LEARN

PRODUCTS

OPEN SOURCE

LEARN