Docs Menu

HTTPS Endpoint Requests & Responsesicons/link.png

On this page

  • Overview
  • Request Validation Methods
  • Payload Signature Verification
  • Secret as a Query Parameter
  • HTTPS Endpoint Response Object

HTTPS Endpoints offer several ways to validate requests and customize the response that MongoDB Realm returns to the caller.

There are two types of Request Validation for endpoints: Payload Signature Verification and Secret as a Query Parameter.

Note

For maximum security, programmatically generate the secret string using a secure package such as the Python secrets module. Make sure that you do not publish the secret or include it in your version control system.

The Verify Payload Signature request validation option requires that incoming requests include a hexadecimal-encoded HMAC SHA-256 hash generated from the request body and secret string in the Endpoint-Signature header.

Example

Consider the following endpoint request body and secret:

const body = { "message":"MESSAGE" }
const secret = 12345

The following Realm Function generates the hash for this body and secret:

// Generate an HMAC request signature
exports = function(secret, body) {
// secret = the secret validation string
// body = the endpoint request body
return utils.crypto.hmac(EJSON.stringify(body), secret, "sha256", "hex");
}
// Returns: "828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862"

The hash value must be assigned to the Endpoint-Signature HTTP request header on every request:

Endpoint-Signature::sha256=<hex-encoded-hash>

To test that the request was properly signed, we could run the following curl command:

curl -X POST \
-H "Content-Type: application/json" \
-H "Endpoint-Signature::sha256=828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862" \
-d '{"message":"MESSAGE"}' \
<endpoint URL>

The Require Secret as Query Param request validation option requires that incoming requests include the specified secret string as a query parameter appended to the end of the URL.

Example

Consider a endpoint configured to use a secret value of 12345. All requests must be made to the endpoint URL appended with the secret as a query parameter:

<endpoint URL>?secret=12345

To test that requests to this URL are properly verified, we could run the following curl command:

curl -H "Content-Type: application/json" \
-d '{ "message": "HELLO" }' \
-X POST '<endpoint URL>?secret=12345'

Realm automatically passes a response object that represents the endpoint's HTTP response as the second argument to endpoint Function. The following table lists the available methods for modifying the response object:

Method
Arguments
Description
setStatusCode(code)
code integer

Set the HTTP response status code.

Example
response.setStatusCode(201);
setBody(body)
body string or BSON.Binary

Set the HTTP response body.

If body is a string, it will be encoded to BSON.Binary before being returned.

Example
response.setBody(
"{'message': 'Hello, World!'}"
);
setHeader(name, value)
name string
value string

Set the HTTP response header specified by name to the value passed in the value argument. This overrides any other values that may have already been assigned to that header.

Example
response.setHeader(
"Content-Type",
"application/json"
);
addHeader(name, value)
name string
value string

Set the HTTP response header specified by name to the value passed in the value argument. Unlike setHeader, this does not override other values that have already been assigned to the header.

Example
response.addHeader(
"Cache-Control",
"max-age=600"
);
response.addHeader(
"Cache-Control",
"min-fresh=60"
)
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.