Custom Registration v1

Authentication

These endpoints require HTTP Basic Authentication with the Client Credentials of the Client that triggers the Custom Registration.

Init Request

The Init Step is only used for the TWO_STEP flow. The ONE_STEP flow uses the Complete Step.

Endpoint: POST /oauth/custom-registration/{idp}/init

Parameter	Description
idp	Identity provider identifier

JSON body parameters:

Param	Required	Description
data	no	Raw registration request data which will be provided to the OneWelcome Extension Engine

Example request:

POST /oauth/custom-registration/example-custom-registration-idp/init HTTP/1.1
Host: onewelcome.example.com
Content-Type: application/json
Authentication: Basic Y2xpZW50OnNlY3JldA==

{
    "data": "{\"custom_json_key\":\"custom json data\"}" // optional
}

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "transaction_id": "123123",   //something unique, should be passed with complete step
   "data": "12349876",           // e.g. a challenge code.
   "status": 2000
}

In the event of an error in the Access Service, one of the following error codes will be returned.

It is up to the scripts executed by the Extension Engine to determine if the request was successful or not when everything looks fine for the Access Service. For all these scenarios, a 200 OK JSON response returned to the SDK which contains:

Param	Description
transaction_id	Generated in Init step. For TWO_STEP, ensures same transaction
data	Raw response coming from the script engine
status	Status indicating whether the request was successful. See status codes

Complete Step

Endpoint: POST /oauth/custom-registration/{idp}/complete

Parameter	Description
idp	Identity provider identifier

JSON body parameters:

Param	Required	Description
transaction_id	yes (TWO_STEP) otherwise optional	Generated in Init step. For TWO_STEP, ensures same transaction
data	no	Raw registration request data which will be provided to the Extension Engine
scope	no	An array of scopes. If none are specified the default scopes are granted
profile_id	yes (mobile client) otherwise optional	The profile ID of the user on the OneWelcome SDK, static clients can omit this. Profile ID must be 6 characters long.
hook_context_custom_params	no	A map of custom web hooks context parameters used in Web Hooks
grant_type	no	Grant type that the Access Token will be bound with. If not specified, the default grant type will be used. Available values: urn:onewelcome:oauth2:grant_type:stateless_authentication

Example request:

POST /oauth/custom-registration/example-custom-registration-idp/complete HTTP/1.1
Host: onegini.example.com
Content-Type: application/json
Authentication: Basic Y2xpZW50OnNlY3JldA==

{
  "transaction_id": "123123",
  "data": "{\"custom_json_key\":\"custom_ json data\"}",      //optional, e.g. challenge code response
  "scope": ["read", "write"],
  "hook_context_custom_params": {      //optional
     "on_behalf_of" : ["user"]
  }
}

Example successful response

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "status": 2000,
    "oauth_token": {
        "token_type": "bearer",
        "access_token": "8A5AB83A3C6B7AAC41471C1205167A35E0F9281ED277EE2FDE6E8DE30972936D",
        "refresh_token": "8CAE26B2B8E8EC18B4D432886448C7F99B558063C517BA41F30966B37C104983",
        "id_token": "eyJraWQiOiI1Nzk1[...omitted for brevity...]r9KM8c5y-Utpw",
        "expires_in": 3600
    },
    "data": "{\"custom_json_key\":\"custom json data\"}" // optional
}

In the event of an error in the Access Service, one of the following error codes will be returned.

Additional error code for this endpoint:

Server error codes

Status code	Error code	Description
400	invalid_request	Missing required parameter or the request is not correctly formatted.
404	invalid_idp_identifier	The specified IdP does not exist.
403	idp_disabled	The specified IdP is disabled.
400	invalid_client	Not a valid client.
400	invalid_transaction	The transaction is invalid or has expired
400	invalid_scope	The requested scope is invalid, unknown or malformed.

It is up to the script's execution in the Extension Engine to determine if the request was successful or not when everything looks fine for the Access Service. For all these scenarios, a 200 OK JSON response returned to the SDK which contains:

Param	Description
access_token	Access token generated after successful completion of step.
refresh_token	Refresh token generated after successful completion of step and client has them enabled.
expires_in	Time until expiration in seconds.
token_type	Token type.
id_token	ID token with user data if the requested scope contains openid.
data	Raw response coming from the script engine.
status	Status indicating whether the request was successful. See status codes.

Extension engine status codes

Param	Value
VALID_STATUS_MIN	2000
VALID_STATUS_MAX	2999
RETRY_STATUS_MIN	4000
RETRY_STATUS_MAX	4999
UNRECOVERABLE_STATUS_MIN	5000
UNRECOVERABLE_STATUS_MAX	5999