Skip to content
Connect2id

Initial token for client registration

Developers can be issued with one time use tokens to self-register their own OAuth 2.0 / OpenID Connect applications at the clients endpoint of the Connect2id server.

Step 1. Register a proforma public OAuth client for the tokens

Using the master token, or some other token with sufficient rights, register an OAuth 2.0 client to which the initial access tokens for the registration endpoint will be formally issued.

Make sure the client cannot use any OAuth 2.0 grants and is public (has no credential). Give it a descriptive name.

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

{
  "grant_types"                : [],
  "token_endpoint_auth_method" : "none",
  "client_name"                : "Initial reg token client"
}

A sample resulting client registration:

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

{
  "client_id"                  : "mihbycli7x7ay",
  "client_id_issued_at"        : 1504187117,
  "registration_client_uri"    : "https://demo.c2id.com/clients/mihbycli7x7ay",
  "registration_access_token"  : "7ykDWJO481cGp66GddfsNMwwp2TptkTUH1XdgAFx9Yk.Kg",
  "grant_types"                : [],
  "response_types"             : [],
  "client_name"                : "Initial reg token client",
  "token_endpoint_auth_method" : "none"
}

Note the assigned client_id – mihbycli7x7ay. If you don’t like a random value generated by the Connect2id server you can choose your own client_id.

Step 2. Obtain the required initial registration token(s)

Make a call at the direct authorisation endpoint to obtain the actual initial token to pass to the developer for them to self-register (manually or programmatically) her client.

Important:

  • Make sure the token is given a set of suitable client-reg:… scope values to lock the permitted client attributes that may be registered. You would typically want to lock the grant type and the default scope values for the client.

  • The token audience must be set to the Connect2id server issuer URL or the client registration endpoint URL.

  • Make sure the token lifetime (in seconds) is sufficient for the registration time window that you want to allow.

  • The token is valid for one registration only! If the client registration fails due to an invalid parameter, the token will be marked as consumed.

To call the direct authorisation endpoint you will need its master API token. Here is an example request to issue a token for hackaton-attendee-01 valid for 24 hours:

POST /direct-authz/rest/v2 HTTP/1.1
Host: demo.c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub"          : "hackaton-attendee-01",
  "client_id"    : "mihbycli7x7ay",
  "scope"        : [ "client-reg:grant:code",
                     "client-reg:grant:refresh",
                     "client-reg:scope:read",
                     "client-reg:scope:write" ],
  "audience"     : [ "https://demo.c2id.com/clients" ],
  "access_token" : { "lifetime" : 86400,
                     "encoding" : "IDENTIFIER" }
}

The resulting initial access token, the scope parameter details it allows a client registration for the code and refresh_token grant types, and the read write scope values:

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

{
  "access_token" : "HTnb1ySwzI_JjyF601IzAg.pckyCJ563S8qn-Zq5b1nJA",
  "scope"        : "client-reg:grant:code client-reg:grant:refresh client-reg:scope:read client-reg:scope:write",
  "token_type"   : "Bearer",
  "expires_in"   : 86400
}

Step 3. Use the token to self-register the client

The developer can now use this token to register their client. The token must be set in the Authorization header.

Example request to register a client:

POST /clients HTTP/1.1
Host: demo.c2id.com
Authorization: Bearer HTnb1ySwzI_JjyF601IzAg.pckyCJ563S8qn-Zq5b1nJA
Content-Type: application/json

{
  "grant_types"   : [ "code", "refresh_token" ],
  "redirect_uris" : [ "https://example.com/cb" ],
  "client_name"   : "Hello world!",
  "scope"         : "read write"
}

Attempting to reuse the token will result in a 401 error:

HTTP/1.1 401 Unauthorized
Bearer error="invalid_token", error_description="Token already expended"

Don’t worry if the registration request includes grant types or scope values that aren’t permitted - the Connect2id server will automatically trim them to what’s permitted by the initial registration token (instead of returning an error).

Upon successful registration the client will be issued a permanent token, found in the registration_access_token field, to enable self-management of the client registration, for example to modify the client redirection URI or its displayed client name.

Note, the scope of the registration_access_token will be locked to the one set by the initial token. This is to ensure a client cannot change critical attributes, such as its originally allowed OAuth 2.0 grant types or default scope values. For example, if the initial token had a scope value client-reg:grant:code, the client registration cannot be updated to include another grant, e.g. password.