CPcpanel
360 Monitoring

Complete the WebPros authentication flow

Changed on

This function completes the WebPros single sign-on flow for 360 Monitoring.

Call this function after the WebPros authorization server redirects the user back to the server. The function exchanges the authorization code for a token bundle and stores that bundle on the server. It does not return the access token or the refresh token. Use the 360Monitoring/webpros_auth_token function to retrieve the access token.

This function accepts its arguments as a single JSON-encoded json parameter, and it requires that parameter in the request body. The authorization code is a secret, and the server records the URL query string in its access log. The function therefore rejects a request that is not an HTTP POST, and also rejects a json parameter that appears in the query string of a POST.

The function returns data.success with a value of 1 when it stores a token. If the function fails, it returns data.success with a value of 0, a human-readable data.error message, and, for the failures that it detects before it contacts the authorization server, a machine-readable data.reason value.

post/360Monitoring/webpros_auth_callback

Request

  • Base URL
    https://whm-server.tld:2087/json-api
  • Auth
    HTTP basic

Request body application/x-www-form-urlencoded

jsonstring required

A JSON-encoded object that contains the callback arguments.

The object accepts the following keys:

  • code - Required. The authorization code that the WebPros authorization server returned.
  • state - Required. The state value that the WebPros authorization server returned. It must carry the state token that the 360Monitoring/webpros_auth_start function issued for this flow. The system uses this value to confirm that the callback belongs to the flow that this server started.
  • session_id - Optional. The WHM session that this sign-in belongs to, as digits. The system uses this key only when the request itself carries no session, which is the case for callers that authenticate with an API token or with HTTP Basic authentication. A session taken from the request always takes precedence, so a caller inside a session cannot claim a different one.
  • verifier - Ignored. The system keeps the Proof Key for Code Exchange (PKCE) verifier on the server, so 360Monitoring/webpros_auth_start does not return one and this function does not read one. The function accepts this key without error so that existing callers keep working, and a later release will remove it.

The function returns a data.reason value of invalid_json when it cannot decode this parameter or when the parameter does not hold a JSON object, and a data.reason value of missing_parameter when the parameter is absent, when the object does not contain the code key, or when the system cannot determine which WHM session the callback belongs to.

The system verifies the state value before it contacts the authorization server, so it never exchanges the authorization code when the state is absent, does not match, was issued to a different WHM session, or has expired. The stored state is single-use: the system consumes the matching state whether the sign-in then succeeds or fails, which means a callback cannot be replayed and a retry requires a new call to 360Monitoring/webpros_auth_start. A callback whose state matches no sign-in in progress consumes nothing, and neither does one whose state was issued to another administrator's session, so a callback cannot cancel a sign-in that someone else started.

Example request

{
  "json": "{\"code\":\"SplxlOBeZQQYbYS6WxSbIA\",\"state\":\"Xk7fQ2mR9vLpN4wCbT8yHzA1sD6gJ3eU0iO5nY7kV2q\"}"
}

Response

The HTTP Request succeeded.

Example response

{
  "data": {
    "error": "The “code” parameter is required.",
    "reason": "missing_parameter",
    "success": 1,
    "token_data": {
      "email": "user@example.com",
      "expires_in": 900
    }
  },
  "metadata": {
    "command": "webpros_auth_callback",
    "namespace": "360Monitoring",
    "reason": "OK",
    "result": 1,
    "version": 1
  }
}

Changes