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 configuration reference for this action.

​
Supported Phases

on_http_request

​
Type

basic-auth

​
Configuration Fields

​
credentials
array of strings
Required
Supports CEL

A list of up to 10 allowed username:password credential pairs.

Password must be at least 8 characters and no more than 128 characters.

​
realm
string
default:ngrok

The HTTP realm of the request as per RFC 7235.

​
enforce
bool
default:true
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. 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 <credentials>, where <credentials> 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

​
Examples

​
Basic Example

The following Traffic Policy configuration is an example configuration of the basic-auth action.

​
Example Traffic Policy Document

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= 
$ curl --request GET \
  --url http://example-api.ngrok.app/ \
  --header 'Authorization: Basic dXNlcjpwYXNzd29yZDE=`'

HTTP/2 200 OK
content-type: text/html
Successfully Authenticated!
...
In this example, we are sending a request to our 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.
​
actions.ngrok.basic_auth.credentials.presented
bool

Whether there were Basic Auth credentials presented in the Authorization header.

​
actions.ngrok.basic_auth.credentials.username
string

The username of the credentials presented.

​
actions.ngrok.basic_auth.credentials.authorized
bool

Whether the presented basic auth credentials were authorized for this request.