Connect to an HTTP Resource
To connect to an HTTP Resource, follow these steps:-
Adjust the Hostname: In your API request, modify the hostname to point to the Connector. Replace the hostname with the http resource name you have specified in the resources section of the Formal dashboard or Terraform. If the hostname of your connector is
formalcloud.net, and your http resource name isstripe, you can replace the request URL with the following:- Old Way:
https://api.stripe.com/v1/customers - New Way (Using the Connector):
https://stripe.formalcloud.net/v1/customers
- Old Way:
- Tool of Your Preference: Use your preferred API tool to send requests through the Connector. This can be tools like Postman, cURL, or any other HTTP client that allows you to specify the API endpoint. In order to see the user who made the request, you can set
X-Formal-User-UsernameandX-Formal-User-Passwordin the request headers.
Payload Encryption
The Connector encrypts both response and request payloads before they’re sent to the Formal Control Plane. This ensures that Formal won’t have access to any transmitted data. Create a log configuration to enable payload encryption.Decrypting the logs in Formal UI
- First, deploy the AWS Lambda function using the code found here.
- Then, navigate to a specific HTTP Log and hit the
Decrypt Response BodyorDecrypt Request Bodyto input the URL of the Lambda function directly in the UI.
Automatic detection of PII
The Connector can automatically detect PII in request and response JSON payloads such that policies can be applied to redact or block such traffic. To do so, the Connector employs machine learning models hosted by the Data Classifier Satellite. You can choose whether the Satellite should use an LLM model or a custom NLP model built by Formal in its startup options. The Connector supports dynamically choosing the model using HTTP header. You can set theX-Formal-Request-Pii-Classifier and X-Formal-Response-Pii-Classifier headers to llm, nlp, or none to choose the model type. If the header is not set, the Connector will use the NLP model.
HTTP Payload Size Limitation
To ensure efficient and streamlined logging while preventing potential issues related to large data volumes, our system provides configurable size limitations for both HTTP request and response payloads. If the size of a payload exceeds the configured limit, it will not be included in the logs. Create a log configuration to enable limits on payload sizes.Multiple Resources
The Connector supports connecting multiple downstream APIs to the same Connector. For example, using a Connector with the hostnametest-http-proxy.formalcloud.net, you can query:
1
First Step
Configure your DNS entries with the subdomains.
2
Second Step
Create HTTP resources with names matching the subdomains used in the hostname of the Connector. In the example provided, the names of the resources should be
openai and stripe.3
Third Step
Link multiple resources to the same port.
The TLS Certificate must be a wildcard certificate and should cover every subdomain.
Policy Evaluation
Formal supports the following policy evaluation stages for HTTP:- Session: Evaluate and enforce policies at connection time
- Pre-Request: Evaluate and enforce policies before request execution
- Post-Request: Evaluate and enforce policies after data retrieval
Authentication
The Connector supports forwarding HTTP authentication headers transparently from HTTP clients. In addition, the Connector supports adding HTTP authentication headers that the HTTP client does not have access to using Native Users.Native Users
To create native users, a JSON object is used as the password. Formal Connector with HTTP Resource supports various authentication methods, includingBasic, API Key, and Bearer Token.
- Basic Authentication: This method is suitable for scenarios where a simple username and password are adequate for authentication. The configuration for Basic Authentication in Formal is as follows:
{"type": "http", "sub_type": "basic", "http_basic": { "header": "Authorization", "username": "<username>", "password": "<password>"}}
- API Key: When using an API key for authentication, you can specify the key in the request header. This method is typically used when interacting with APIs that require a secret key for access. The configuration is as follows:
{"type": "http", "sub_type": "api_key", "http_api_key": { "type": "header", "key": "Authorization", "value": "<value>"}}
- Bearer token: Bearer Token authentication is a common method used in OAuth 2.0 and other authorization frameworks. It involves sending a token in the request header to authenticate requests. The configuration for Bearer Token authentication in Formal is:
{"type": "http", "sub_type": "bearer_token", "http_bearer_token": { "header": "Authorization", "token": "<token>"}}
The corresponding authentication details will then be passed to the underlying resource, ensuring that access is securely controlled based on the specified method.
Types
Authentication
| Name | Type |
|---|---|
| type | STRING |
| sub_type | ENUM[“http_bearer_token”, “http_api_key”, “http_basic”] |
| http_bearer_token | BearerToken |
| http_api_key | ApiKey |
| http_basic | Basic |
Api Key
| Name | Type |
|---|---|
| type | ENUM[“query_params”, “header”] |
| key | STRING |
| value | STRING |
Bearer token
| Name | Type |
|---|---|
| header | STRING |
| token | STRING |
Basic
| Name | Type |
|---|---|
| header | STRING |
| username | STRING |
| password | STRING |