> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Basic Auth Action
> Enforce HTTP Basic Auth on your endpoints.
export const ConfigField = ({title, type, cel = false, defaultValue = false, required = false, children}) => {
const id = `config-${title.replace(/\.|\s|\*/g, "_")}`;
return
{title}
{type &&
{type}
}
{defaultValue &&
default:
{defaultValue}
}
{required &&
Required
}
{cel &&
Supports CEL
}
{children}
;
};
The Basic Auth action enables you to enforce HTTP Basic Auth on your endpoints. Requests with a valid username and password will be sent to
your upstream service, all others will be rejected with a `401 Unauthorized` response.
## Configuration reference
This is the [Traffic Policy](/traffic-policy/) configuration
reference for this action.
### Supported phases
`on_http_request`
### Type
`basic-auth`
### Configuration fields
A list of up to 10 allowed username:password credential pairs.
Password must be at least 8 characters and no more than 128 characters.
The HTTP realm of the request as per RFC 7235.
If false, continue to the next action even if basic authentication failed.
This is useful for handling fall-through, debugging, and testing purposes.
## Behavior
The **basic-auth** action enforces HTTP Basic Authentication on incoming requests, as specified
in [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235). When a request is received, the action
verifies the request by validating against a known set of `user:password` credentials. If the
verification is successful, the action allows the request to continue through the action chain and
finally to your application; if verification fails, the request will be terminated with a
`401 Unauthorized` response.
### Additional restrictions
You can specify up to 10 `username:password` pairs. The password must be at least
8 characters and no more than 128 characters. Including multiple colons in the `username:password`
pair will result in the first colon being treated as the delimiter between the username and password.
Realm cannot exceed 128 characters, and cannot contain non-ASCII characters.
### Verification process
* **HTTP Authentication**: The action validates incoming HTTP requests to confirm they contain the required `Authorization` header, in the form of `Authorization: Basic `, where `` is the Base64 encoding of username and password joined by a single colon `:`.
* **Request Handling**: If the authentication is successful, the request is forwarded to the next action. If the authentication fails, it will return to user a `401` response, which will prompt the user to provide a correct set of credentials.
* **Configurable Enforcement**: By default, authentication failures result in 401s. However, setting `enforce: false` allows unauthenticated requests to proceed, while logging the authentication result. This option is for debugging and testing.
### Secret handling and encryption
All secrets used for basic authentication are encrypted at config validation. When ngrok processes a request, the secret is decrypted.
### Using CEL in credentials
You can use CEL interpolation in credentials, but the expression must stay properly scoped. A CEL expression can:
* produce the entire credential,
* produce the whole username or password, or
* produce part of the username or password.
If the expression does not produce the entire credential, you must include the `:` separator literally, and the expression itself cannot introduce another colon.
#### Valid patterns
* `${CEL_EXPRESSION}` - Entire credential is dynamic
* `${CEL_EXPRESSION}:password` - Dynamic username, literal password
* `${CEL_EXPRESSION}:${CEL_EXPRESSION}` - Both username and password are dynamic
* `user-prefix${CEL_EXPRESSION}:password` - Part of the username is dynamic, literal password
#### Invalid patterns
* `${CEL_EXPRESSION}password` - Missing colon separator between username and password
* `user-prefix${CEL_EXPRESSION}password-suffix` - Missing colon separator between username and password
### Non-terminating action
This is a **Non-terminating action**. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All **Cloud Endpoint** Traffic Policies must end with a terminating action. This requirement does not apply to **Agent Endpoints**.
## Examples
### Basic example
The following [Traffic Policy](/traffic-policy/)
configuration is an example configuration of the `basic-auth` action.
#### Example Traffic Policy document
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: "basic-auth"
config:
realm: "sample-realm"
credentials:
- "user:password1"
- "admin:password2"
enforce: true
- type: "custom-response"
config:
status_code: 200
headers:
content-type: "text/plain"
body: "Successfully Authenticated!"
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "basic-auth",
"config": {
"realm": "sample-realm",
"credentials": [
"user:password1",
"admin:password2"
],
"enforce": true
}
},
{
"type": "custom-response",
"config": {
"status_code": 200,
"headers": {
"content-type": "text/plain"
},
"body": "Successfully Authenticated!"
}
}
]
}
]
}
```
### Example request
First, base64 encode the `username:password` pair.
`user:password1` becomes `dXNlcjpwYXNzd29yZDE=`
```bash theme={null}
$ curl --request GET \
--url http://example-api.ngrok.app/ \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZDE=`'
```
```http theme={null}
HTTP/2 200 OK
content-type: text/html
Successfully Authenticated!
...
```
In this example, a request is sent to the API with a valid set of credentials in
the `Authorization` header with the `Basic` prefix and getting back a `200 OK`
response.
You can try it without the header, and you will receive a `401 Unauthorized` prompt
instead.
## Action result variables
The following variables are made available for use in subsequent expressions and
CEL interpolations after the action has run. Variable values will only apply
to the last action execution, results are not concatenated.
Whether there were Basic Auth credentials presented in the Authorization header.
The username of the credentials presented.
Whether the presented basic auth credentials were authorized for this request.