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.

Supported Phases

on_http_request

Type

basic-auth

Configuration Fields

• credentialsarray of stringsRequired

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

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

• realmstring

  The HTTP realm of the request as per RFC 7235.

  Default is ngrok.

• enforcebool

  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.

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.

• actions.ngrok.basic_auth.credentials.presentedbool

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

• actions.ngrok.basic_auth.credentials.usernamestring

  The username of the credentials presented.

• actions.ngrok.basic_auth.credentials.authorizedbool

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