Dynamic client registration

Dynamic client registration

This topic explains process of Dynamic client registration. There is no UI for this part, because this process will be performed by application instance automatically.

Registration process

On application instance startup, it will need to register itself through registration endpoint. Endpoint does not require Authentication.

Example of HTTP call

POST /v1/registration HTTP/1.1
Host: ocms.retailsvc.com
Content-Type: application/json; charset=utf8

{
  "softwareId": "te",
  "softwareVersion": "1.0",
  "softwareStatement": "eyJhbGciOiJIUzI1NiIsImtpZCI6IkdDUF9LTVNfS2V5SWQiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2NsaWVudC1tYW5hZ2VyLnJldGFpbHN2Yy5jb20iLCJpYXQiOjE2MTAzNzQ4NzQsImV4cCI6MTYxNjQ1ODg3NCwiY3JlYXRlZF9ieSI6ImFsaWNlQHRlbmFudC5jb20iLCJjbGllbnRfdHlwZSI6IlRFIiwidGVuYW50X2lkIjoiQ0lSN25Rd3RTMHJBNnQwUzZlamQiLCJncmFudF90eXBlcyI6WyJjbGllbnRfY3JlZGVudGlhbHMiXSwidmFsaWRhdG9ycyI6W3siS2V5IjoiaXNvX2NvdW50cnlfY29kZSIsIlZhbHVlIjoiU0UifSx7IktleSI6InN0b3JlX2lkIiwiVmFsdWUiOiI1NDMyIn1dfQ.MS72Bw_KkVAn2EwAQvUYZI7yShqrj9tVEbj0t_5Ytw4",
  "tenantId": "CIR7nQwtS0rA6t0S6ejd",
  "usingGlobalTemplate": false,
  "claims": {
    "iso_cc": "se-SE",
    "business_unit_id": "xxxx",
    "workstation_id": "0001"
  }
}

Claims provided as an example, exact list of claims that you need to provide is defined by registration template that is used in request (softwareId and softwareVersion are an id and version of template)

Example response -

{
  // base64url encoded list of claims + tenantID + sfw (id + version)
  // must be stored securely by app, and used to fetch JWT tokens
  "clientId": "YnVzaW5lc3NfdW5pdF9pZDogdGVzdC1idXNpbmVzcy11bml0LWlkCmlzb19jYzogc2UtU0UKc2Z3OiB0ZUB2MV90ZXN0CnRpZDogMnAwVTJvZ1luRUZKQ3l5d2NuSTgKd29ya3N0YXRpb25faWQ6ICIwMDQyIgo",
  "softwareId": "te",
  "softwareVersion": "1.0",
  "tenantId": "CIR7nQwtS0rA6t0S6ejd",
  // status will be pending, if during registration SS did not have `autoApprove` flag on
  "status": "Pending",
  // must be stored securely by app, and used to fetch JWT tokens
  "clientSecret": "string",
  // must be stored securely by app, and used to manage client itself (delete, read configuration)
  "registrationAccessToken": "string",
  // use GET {registrationClientUri} to get client info and PUT {registrationClientUri}/revoke to cleanup client.
  "registrationClientUri": "http://localhost/example/path/to/client",
  // SS id, if used
  "softwareStatementId": "string",
  "usingGlobalTemplate": true,
  "claims": {},
  // url, where you can retrieve JWT token.
  "authUrl": "string"
}

Errors

Endpoint may respond with body, that will contain error code, that might explain the problem.

Table of Error codes -

Code	Name	Description
EC001	TenantIdNotValid	Tenant id is not valid
EC002	StatementRevoked	Software Statement was revoked
EC003	ClaimsDoNotMatch	Claims in request body do not match the claims in Software Statement or Registration Template
EC004	StatementIsMalformedOrInvalid	Software Statement is malformed or tenantId, softwareId/softwareVersion does not match with Software Statement
EC005	StatementNotFound	Software Statement not found
EC006	RegistrationTemplateNotFound	Registration Template not found
EC007	TemplateScopeMismatch	Template used for creating Software Statement and for registration must have the same scope (either global or for same tenant)
EC008	ClientIdTooLong	The resulting client id exceeds a limit. template id & version & claims make up the client id. It must be <= 255 chars

Get client info

App can also request information about OAuth client that it uses. Possible use case: Pull client status, to start fetching JWT tokens, once client is approved.

Example of HTTP call

GET /v1/registration/{clientId} HTTP/1.1
Host: ocms.retailsvc.com
Content-Type: application/json; charset=utf8
Authorization: Bearer {registrationAccessToken}

Response will be similar to registration response, but it will not include secrets.

Example:

{
  "clientId": "YnVzaW5lc3NfdW5pdF9pZDogdGVzdC1idXNpbmVzcy11bml0LWlkCmlzb19jYzogc2UtU0UKc2Z3OiB0ZUB2MV90ZXN0CnRpZDogMnAwVTJvZ1luRUZKQ3l5d2NuSTgKd29ya3N0YXRpb25faWQ6ICIwMDQyIgo",
  "softwareId": "te",
  "softwareVersion": "1.0",
  "tenantId": "1.0",
  "registrationClientUri": "string",
  "softwareStatementId": "string",
  "usingGlobalTemplate": true,
  "claims": {},
  "status": "Pending"
}

Cleanup OAuth client

App may choose to cleanup oauth client after shutdown.

Example request:

PUT /v1/registration/{clientId}/revoke HTTP/1.1
Host: ocms.retailsvc.com
Content-Type: application/json; charset=utf8
Authorization: Bearer {registrationAccessToken}

Automatic client cleanup

By default if client was not approved in 14 days it will be automatically revoked. Similarly revoked clients will be deleted after 14 days.

This intervals can be customized by setting revokedExpiresIn and pendingExpriresIn fields on Registration Template. See OpenAPI spec for more details.