Basic Authentication

Overview

The Basic Auth Traffic Policy 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.

Action Type

basic-auth

Configuration Fields

Parameter	Type	Description
credentials	string[]	A list of allowed username:password credential pairs. Passwords must be at least 8 characters and no more than 128 characters.
realm	string	The HTTP realm of the request as per RFC 7235. Default is ngrok.
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.

Supported Phases

• on_http_request

Supported Schemes

• https
• http

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 only a limited number of 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.

Examples

Basic Example

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

Example Traffic Policy Document

YAML

---
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"
          content: "Successfully Authenticated!"

JSON

{
  "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"
            },
            "content": "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.

Name	Type	Description
actions.ngrok.basic_auth.credentials.presented	boolean	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	boolean	Whether the presented basic auth credentials were authorized for this request