Registration

The registration API allows the client applications to register their callback information (including the callback URL) in the system. Also, the client application can specify the callback authentication method.

The client application uses the user credentials to register on the system. Upon successful registration, the client application can receive notifications.

Register API client with callback information describes the API structure for the registration process.

Note: IMPACT supports both http and https in callback URL of the request body.
Note: By configuring the IP or the IP range for the System Setting url.ip.range.prevention, vulnerable callback servers can be blacklisted. Configuring this will restrict the user registration to this IP.

Table 1. Register API client with callback information
Title Register API client with callback information
URL http://<impact_url>/m2m/applications/registration
Method PUT
Content-Type application/json
URL Params The following are the URL parameters:

  • registrationInput:[body]: Registration body specifies the Base64 encoded authorization in header and URL for callback. It consists of the following parameters:

    • headers:[composite]: Specifies the authorization header.

      • callbackAuth:[string]: Indicates the authorization type used by the call back server. If the callback server uses HTTP digest authorization, set this parameter to Digest.

        If the callback server uses basic authorization, do not use this parameter.

        Example:

        "headers":{"authorization":"Basic dXNlcjE6dXNlcjFQYXNz", "callbackAuth":"Digest"}

    • url:[string]: Specifies the callback URL to be provided for notifications.

    • payloadSize:[integer]: Indicates an optional parameter, which is introduced to configure the payload size at the user level at the time of registration.
Data Params Msg:[String]: info/warning/error message
Success Code 
Response Code: 201
Error Code 
400 : Bad Request
401 : Unauthorized 
403 : Forbidden 
404 : Not Found
Sample Call

Curl:

Callback server uses HTTP digest authorization:

curl -X PUT
        --header 'Content-Type: application/json' --header 'Accept: application/json'  --header 'Authorization: Basic ZG9jdXNlcjpBc2RmMSM=' -d
        '{"url":"http://localhost:8080/applications/callback/impact", 
 "headers":{"authorization":"Basic dXNlcjE6dXNlcjFQYXNz", "callbackAuth":"Digest"} 
}' 'http://<impact_url>/m2m/applications/registration'

Callback server uses Basic authorization:

curl -X PUT
        --header 'Content-Type: application/json' --header 'Accept: application/json'  --header 'Authorization: Basic ZG9jdXNlcjpBc2RmMSM=' -d
        '{  "headers": {"authorization":"Basic
        dWF0YWRlcDpBc2RmMSM="},  "url":
        "http://<callback_url>/m2m/impact/callback"
    }' 'http://<impact_url>/m2m/applications/registration'

Callback server uses OAuth authorization:

curl -X PUT
   --header 'Content-Type: application/json' --header 'Accept: application/json'  --header 'Authorization: Basic ZG9jdXNlcjpBc2RmMSM=' -d
{
"headers": {
"clientId": "myapp",
"secret": "08e8de15-ec96-42ed-aa17-9c04c9ba01c4",
"callbackAuth": "OAuth",
"AuthUrl": "http://localhost:8080/auth/realms/demo/protocol/openid-connect/token"
"scope": "api://{clientId}/.default"
},
"url": "http://localhost:8080/auth/realms/demo/protocol/openid-connect/token"
}
Where:
  • The clientId and secret are the client credentials provided by the OAuth server.
  • The callbackAuth defines the authentication type.
  • The AuthUrl is the URL of the authorization server.
  • The url is the URL of the callback server.
  • The Scope parameter is an optional parameter, which is only required in the case of the Azure Active Directory.

    If the Azure OAuth 2.0 token endpoint (v2) is used, then the Scope parameter is required.

    If Azure OAuth 2.0 token endpoint (v1) is used, then the Scope parameter is optional.

Response Body:

{
"msg": "Success","code":1000
}
Notes

The system automatically checks the correctness of the callback URL that is, the client application is available at the address during registration.

When using SSL with HTTPS, the certificate of the application has to be valid or this correctness check will fail. This uses a GET method to achieve this which must be treated as success.