How to issue and use an initial access token for client registration

Developers can be issued with an access token to self-register their own OAuth 2.0 or OpenID Connect client with the Connect2id server.

Step 1. Register 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 is cannot use any OAuth 2.0 grants and is public (has no credential). Give it some descriptive name.

POST /c2id/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/c2id/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.

Step 2. Obtain required initial access token(s)

Make a call at the direct authorisation endpoint to obtain the actual initial token which you can then give to the developer to self-register her client.

Important points:

• Make sure the token is given the client-reg scope value, or some other suitable scope value to determine what kind of client attributes may be registered with the token. You would typically want to lock down 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 also be marked as consumed.

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

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

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

The resulting initial access token:

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

{
  "access_token" : "HTnb1ySwzI_JjyF601IzAg.pckyCJ563S8qn-Zq5b1nJA",
  "scope"        : "client-reg",
  "token_type"   : "Bearer",
  "expires_in"   : 86400
}

Step 3. Use initial token to self-register 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 /c2id/clients HTTP/1.1
Host: demo.c2id.com
Authorization: Bearer HTnb1ySwzI_JjyF601IzAg.pckyCJ563S8qn-Zq5b1nJA
Content-Type: application/json

{
  "redirect_uris" : [ "https://example.com/cb" ],
  "client_name"   : "Hello world client"
}

Upon successful registration the client will be assigned another registration token, found in the registration_access_token field, which can be used to manage the registration, e.g. to modify the displayed client name.

Note that scope of that token will be locked down to the one set by the initial token. This done to ensure a client cannot update its details to use some other OAuth 2.0 grant than the one which was originally permitted. 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.