Bcauthorize Endpoint

Clients can create a request for Client Initiated Backchannel Authentication (CIBA) feedback on operations such as a push-based logon on a mobile device.

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/bcauthorize [POST]
Note: This endpoint only supports bearer token authentication. It does not support basic authentication.

For further information about CIBA deployment, see the push-based solution's Enable Validation Feedback using CIBA Notifications and CIBA Demo Portal Sample.

For detailed responses, see Retrieve the Authentication Result and Access Token.

Bcauthorize Request

Copy 
POST https://[base-server-url]/{tenant}/authn/bcauthorize HTTP/1.1
Connection: close
Authorization: Bearer RTp7HwAAAXk3s41v8uBOEA92yE98qTLB1+SKlONh
Content-Type: application/x-www-form-urlencoded
 
{
     "scope": "openid hid-tx-sign",
     "acr_values": "mod-mf",
     "login_hint_token": "eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfVERTIiwidGRzIjoie2Ftb3VudCwgNDAwLjAwfSx7c29ydGNvZGUsMjAtMzAtOTB9LCB7YWNjb3VudF90bywxMjM0LTU2Nzh9IiwiY2hhbm5lbCI6IkNIX1REUyIsInVzZXJjb2RlIjoiYmFua3VzZXIwMSIsImRldmljZWlkIjoiMTEwNTgiLCJjcmVhdGVTZXNzaW9uIjoiMSJ9."
 }

Where:

  • scope – is the scope that defines the list of claims (user information) that will be part of the id_token

    The hid-tx-sign scope adds support for custom claims, such as "JWS", "PUK", "approvalstatus" , "deviceid" , "domain".

  • login_hint_token – is a JWT token (PlainJWT with no signature or encryption) with the information required to initiate a push-based logon or operation validation approval

    Copy

    The JWT JSON payload of login_hint_token is:

    {
        "authpol":"AT_PASA",
        "tds":"Please validate Logon",
        "channel":"CH_DIRECT",
        "usercode":"MyTestUser",
        "deviceid":"11924",
        "createSession":"0",
        "RMSInfo":"eyJhbGciOiJub25lIn0.eyJUTV9TRVNTSU9OX1NJRCI6InJZRmNtNjVwa2hvYXdHUkZnTjFVUk5YWUhsM1FBcGxIIiwiVE1fQ0xJRU5UX0lQIjoiMTAuMTYuNzEuNzkiLCJUTV9TRVNTSU9OX1RSQU5TRkVSIjoiUFc4RDBUUDVrMmFHZEl2TUlYcU5LM2ZCZ1NnNWVCVjdYSEFIOHNneCIsIlRNX0RFVklDRV9UQUciOiIwT2VuTnFBZGxRM2Fwb1ZmSGhkcmJuZ2F2WDRVajNQVCJ9."
    }

    Where:

    Parameter Description

    usercode

    The ActivID Appliance identifier of the targeted user

    This is not required for userID-less QR code operations.

    deviceid

    The ActivID Appliance identifier of the targeted device

    If not set, the notification is sent to the last used device (the active device that has the most recently used credential for the authentication policy in the request).

    This is not required for userID-less QR code operations.
    authpol

    The authentication policy to use
    channel

    The channel to create the logon or operation request on the ActivID Appliance (optional, the default is the channel configured for the OpenID client)
    tds

    (Optional) The logon or operation validation message to be displayed on the device for approval

    createSession

    (Optional) Defines if ActivID Appliance will create a sessionid (aka ALSI) if the operation is validated on the device

    • If set to "1", then a sessionid will be created

    • The default value is "0" (no session is created)

    mode

    Required to indicate that the request is for a userID-less QR code operation and you should set the value to userid_less.

    This is not required for userID-based requests.

    device_type

    Required for a userID-less QR code operation to identify the keyID and you should specify the push-based device type.

    This is not required for userID-based requests.

    cal

    (Optional) Specifies the default approval status sent to the device for a userID-less QR code operation.

    This should be a subset (string) of the values defined for the push-based credential type (where the default value is accept|deny|report).

    If you set the parameter to accept, the request will be automatically signed and the user will not be prompted to approve or decline.

    RMSInfo

    (Optional) A PlainJWT object with information in the context of Risk Management System integration (for further information, see refer to the ActivID Risk Management Service Integration Guideavailable from the ActivID Customer Portal). The following is an example of the content:

    Copy 
    {
      "TM_CLIENT_IP": "10.16.71.79",
      "TM_SESSION_SID": "rYFcm65pkhoawGRFgN1URNXYHl3QAplH",
      "TM_DEVICE_TAG": "0OenNqAdlQ3apoVfHhdrbngavX4Uj3PT",
      "TM_SESSION_TRANSFER": "PW8D0TP5k2aGdIvMIXqNK3fBgSg5eBV7XHAH8sgx"
                            }
    Copy

    Example of login_hint_token for a userID-less QR code operation:

    eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJ0ZHMiOiJ0cmFuc2FjdGlvbkRhdGEiLCJhdXRocG9sIjoiQVRfUEFTQSIsImNoYW5uZWwiOiJDSF9FWFRSQVBQIiwiZGV2aWNlX3R5cGUiOiJEVF9URFNWNCIsImNhbCI6ImFjY2VwdCIsIm1vZGUiOiJ1c2VyaWRfbGVzcyJ9.

    Copy

    The JWT JSON payload of login_hint_token is:

    {
        "tds": "transactionData",
        "authpol": "AT_PASA",
        "channel": "CH_EXTRAPP",
        "device_type": "DT_TDSV4",
        "cal": "accept",
        "mode": "userid_less"
    }

    Copy

    Example of login_hint_token without the optional RMSInfo:

    eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfUEFTQSIsInRkcyI6IlBsZWFzZSB2YWxpZGF0ZSBMb2dvbiIsImNoYW5uZWwiOiJDSF9ESVJFQ1QiLCJ1c2VyY29kZSI6Ik15VGVzdFVzZXIiLCJkZXZpY2VpZCI6IjExOTI0IiwiY3JlYXRlU2Vzc2lvbiI6IjAifQ.

    Copy

    The JWT JSON payload of login_hint_token is:

    {
        "authpol":"AT_PASA",
        "tds":"Please validate Logon",
        "channel":"CH_DIRECT",
        "usercode":"MyTestUser",
        "deviceid":"11924",
        "createSession":"0"
    }

Bcauthorize Request (Push Mode Only)

Copy 
POST https://[base-server-url]/{tenant}/authn/bcauthorize HTTP/1.1
Connection: close
Content-Type: application/json
Authorization: Bearer RTp7HwAAAXk3s41v8uBOEA92yE98qTLB1+SKlONh
 
{
    "scope": "openid hid-tx-sign",
    "acr_values": "mod-mf",
    "client_notification_token": "8d67dc78-7faa-4d41-aabd-67707b374255",
    "login_hint_token": "eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfVERTIiwidGRzIjoie2Ftb3VudCwgNDAwLjAwfSx7c29ydGNvZGUsMjAtMzAtOTB9LCB7YWNjb3VudF90bywxMjM0LTU2Nzh9IiwiY2hhbm5lbCI6IkNIX1REUyIsInVzZXJjb2RlIjoiYmFua3VzZXIwMSIsImRldmljZWlkIjoiMTEwNTgiLCJjcmVhdGVTZXNzaW9uIjoiMSJ9."
}

Where the additional client_notification_token parameter is specific to the push mode and is a token generated by the client application that will allow to authenticate the ActivID Appliance server calling for the notification callback.

Bcauthorize Response

Copy 
HTTP/1.1 200 OK
Cache-Control: no-store
X-XSS-Protection: 1; mode=block
Pragma: no-cache
X-FRAME-OPTIONS: DENY
Content-Type: application/json; charset=UTF-8
Content-Length: 84
 
{
    "auth_req_id": "a95c61e0-f604-4905-98b1-26b7b87fe073",
    "interval": 5,
    "expires_in": 120
}

Where:

  • auth_req_id – is a unique ID (that is, correlationID) generated by ActivID Appliance that identifies the push-based operation in progress

  • expires_in – the validity (in seconds) of the logon or operation validation request on ActivID Appliance

Error Responses

Code Label Possible Errors

400

BAD REQUEST
  • invalid_request
  • unknown_user_id
  • missing_user_code
  • unauthorized_client

401

UNAUTHORIZED

invalid_token

500

INTERNAL SERVER ERROR

transaction_failed

See also:

Configure RADIUS Push-Based Authentication (Optional)