Skip to content
Connect2id

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 request OAuth 2.0 access tokens.

Client registration is specified in:

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 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 (requires plugin). 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). This permissive scope value must be used with caution and may be discontinued in future for safety reasons.
    • 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.
    • client-reg:set-sector-id-urn – Permits registration of a client with a sector_identifier_uri client metadata parameter that is a URN for a sector ID managed by the OpenID provider.

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

Resources
Representations Errors

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.

Body:

Success:

Errors:

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",
                                        "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:

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

Errors:

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",
                                        "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 and if configured the client secret as well. When a new client secret is generated the previous one remains valid for another 30 minutes to enable 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.

Body:

Success:

Errors:

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",
                                     "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. All refresh tokens, access tokens and long-lived (persisted) authorisations for the client will be revoked / deleted too.

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: 204

Errors:

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:

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, in the form of 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: 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 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 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