When a user attempts to connect to a cloud computer, we need to identify the user and determine whether they should be granted access.

​
Authentication Strategies

​
Token Authentication

  • This is the default authentication strategy
  • No additional code is needed

​
Webhook Authentication

  • You need to create an endpoint on your backend (i.e. a webhook)
  • The virtual computer will hit your endpoint when a new user tries to connect
  • Your backend’s webhook response controls whether the user is granted access
  • To set the authentication strategy, you provide an authentication object when starting a cloud computer session:

​
Setting the Authentication Strategy

To set the authentication strategy, you provide an authentication object when starting a cloud computer session: Token Authentication (Default) 
{
  "auth": {
    "type": "token"
  }
}
Webhook Authentication 
{
    "auth": {
    "type": "webhook",
    "value": {
      "url": "https://yourwebsite.com/webhook/hyperbeam/auth"
      "bearer": "<cryptographic-key>"
    }
  }
}

​
Request Body

PropertyTypeDescription
auth.typestringThe authentication strategy type. Valid values are webhook and token.
auth.value.urlstringThe endpoint of your webhook for webhook-based authentication.
auth.value.bearerstringA secret cryptographic key you provide to verify the webhook request is coming from Hyperbeam.

​
In-Depth

​
Token Authentication

When using token authentication, a token is added as a query parameter to the cloud computer’s embed URL. This ensures only users that were provided the embed URL have access to the cloud computer—malicious actors cannot gain access via the session ID or brute force.

​
Webhook Authentication

Start a cloud computer session with webhook authentication 
curl -X POST -H 'Authorization: Bearer <your-api-key>' \
    https://engine.hyperbeam.com/v0/vm \
    -d '{
      "auth": {
        "type": "webhook",
        "value": {
          "url": "https://yourwebsite.com/webhook/hyperbeam/auth",
          "bearer": "<secret-key>"
        }
      }
    }'
You will need to create an endpoint on your backend. The cloud computer will send a request to the endpoint you provided to determine if a user is allowed to connect. Our request will:
  • Set the Authorization header to Authorization: Bearer <bearer-token>
    • <bearer-token> is the token you provided in the authentication object
  • Set the HB-User-Agent header to the client’s user agent
  • Set the HB-Connection-IP header to the client’s IP address
  • Send a POST request with a JSON request body 
{
  "user_id": "7411d16b-9451-415e-bb65-7d5ff3202249",
  "userdata": {}
}
TL;DR: our request will look like this: 
curl -X POST -H 'Authorization: Bearer <bearer-token>' \
    -H 'Content-Type: application/json' \
    -H 'HB-User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36' \
    -H 'HB-Connection-IP: 203.0.113.195' \
    https://yourwebsite.com/webhook/hyperbeam/auth \
    -d '{"user_id": "7411d16b-9451-415e-bb65-7d5ff3202249", "userdata": {"my_data": "foo"}}'
Testing webhooks is difficult when running your backend locally (e.g. our cloud computers cannot reach localhost:8080). We recommend using ngrok to expose your endpoint for testing. Your webhook must:
  • Check that the bearer token in the Authorization header matches the token you provided
  • Parse the request body and determine if the user should be granted access
    • You can use the user_id and userdata fields to identify the user
  • Send back a 200 status with a JSON response body
    • To grant user access, send back {"authorized": true}
    • To deny user access, send back {"authorized": false}
    • Any response that doesn’t have a 200 status code will deny user access
    • If the “authorized” key is not set, the user will be denied
    • You can provide a permissions object in the response to atomically set the permission values of the user