Introducing the Basic Auth Traffic Policy action

We're excited to announce our Basic Auth Traffic Policy action that allows you to enforce HTTP Basic Authentication on incoming requests as outlined in RFC 7235. Adding Basic Auth to your application is simple—just specify up to ten sets of credentials and apply the following Traffic Policy rule to your endpoint:

---
on_http_request:
  - actions:
    - type: basic-auth
      config:
          credentials:
            - USERNAME1:PASSWORD1
            - USERNAME2:PASSWORD2

This blog post explains how this action works and how to add it to your Traffic Policy rules. 

How Basic Authentication works

Basic Auth enables a user agent, such as an API client or web browser, to supply a username and password with an HTTP request. ngrok then validates these credentials and forwards authorized requests to your upstream service. 

Let’s look at an example. The traffic policy rule below ensures that only HTTP requests that include the username mandy with the password ngrokrocks can reach your service. 

---
on_http_request:
  - name: Add basic auth
    expressions: [ ]
    actions:
      - type: basic-auth
        config:
          realm: Admin Login
          credentials:
            - 'mandy:ngrokrocks'

You can start an agent endpoint and apply the policy above by saving it to a file and passing it in the following command, substituting the appropriate value for {YOUR_DOMAIN}:

ngrok http 3000 --url={YOUR_DOMAIN} --traffic-policy-file=policy.yaml

Once you run this command, ngrok forwards requests that pass validation to the upstream service at YOUR_DOMAIN, which serves the application running on port 3000 of the host where you ran this command. If the authorization fails, ngrok immediately rejects the request in our global network. You have successfully offloaded authorization to ngrok!

Pass Basic Auth credentials in requests

For non-interactive, programmatic access to your application or service, such as API calls, the client encodes the username and password in Base64, separated by a colon (e.g., mandy:ngrokrocks), and passes it in the request’s Authorization header. You can create this string programmatically or with a Basic Authentication header generator.

Configure the Basic Auth action

You can configure this action using these configuration properties:

• credentials - A list of allowed username:password credential pairs. Passwords must be at least eight characters and no more than 128 characters. You may configure up to 10 sets of credentials. Required.
• realm - The HTTP realm, as per RFC 7235. The default is ngrok. Optional.
• enforce - Whether or not to block unauthorized requests or execute the next Traffic Policy rule—defaults to true. Optional.

If this is false, you can take other actions, like sending a custom response rather than immediately rejecting the request. The action result variable allows you to check whether the verification was successful. Setting this value to false facilitates testing, debugging, and handling fall-through.

Evaluate Traffic Policy results

When the Basic Auth Traffic Policy action executes, it returns an action.ngrok.basic_auth object containing the following properties, which you can reference in subsequent Traffic Policy rules:

• credentials.presented - Whether the request presented Basic Auth credentials in the Authorization header.
• credentials.presented - Whether the request presented Basic Auth credentials in the Authorization header.
• credentials.authorized - Whether the request provided Basic Auth credentials authorized for this endpoint.

When to use the Basic Auth action

Basic Auth is the quickest way to secure your application or service with ngrok, offering an effortless setup without requiring external redirects or complex configurations with third-party auth providers. It's perfect for sharing your project securely without exposing it to the entire internet. 

Basic Auth seamlessly integrates into legacy applications that don’t support higher-level authentication protocols. It also effectively protects internal APIs and facilitates rapid prototyping. While we recommend implementing OAuth or JWT validation for modern production environments, Basic Auth provides an effective layer of protection during development. 

Implement the Basic Auth Traffic Policy action

Let’s apply the same Basic Auth rule discussed above to a cloud endpoint. This example uses the ngrok API, but you can also create and configure cloud endpoints in the dashboard.

---
on_http_request:
  - name: Add basic auth
    expressions: [ ]
    actions:
      - type: basic-auth
        config:
          realm: Admin Login
          credentials:
            - 'mandy:ngrokrocks'
  - actions:
      - type: forward-internal
        config:
          url: https://api.internal
          binding: internal

This example policy forwards requests authenticated with the username mandy and the password ngrokrocks to an internal endpoint at https://api.internal while immediately rejecting unauthorized requests. This rule can be applied using the ngrok dashboard, agent CLI, API, or SDKs.

To apply this policy to a cloud endpoint using the ngrok agent API client, save the policy to a file and run the following command, replacing {YOUR_API_KEY} and {YOUR_DOMAIN} with your specific values:

ngrok api endpoints create \
     --api-key {YOUR_API_KEY} \
     --bindings public \
     --description "Cloud endpoint with Basic Auth" \
     --metadata “basic auth cloud endpoint” \
     --url https://{YOUR_DOMAIN}
     --traffic-policy "$(cat policies.yaml)"

Chain Traffic Policy rules

With traffic policies, you can combine rules, incorporate CEL variables, and conditionally apply actions based on the outcomes of previously executed rules. Let’s extend the example above and apply it to a cloud endpoint.

The following rule sets enforce to false, allowing unauthorized requests initiated programmatically—such as API calls or curl commands—to proceed to the following rule in the Traffic Policy file. This flexibility enables testing and debugging programmatic workflows such as API calls.

The response will include a custom header and the message Verification failed at ${time.now} instead of the default 401 Unauthorized response. 

When authentication succeeds, ngrok forwards the requests to the internal endpoint at https://api.internal.

on_http_request:
  - name: Add basic auth
    expressions: [ ]
    actions:
      - type: basic-auth
        config:
          realm: Admin Login
          credentials:
            - 'mandy:ngrokrocks'
          enforce: false
  - name: debug unauthorized request
    expressions:
      - actions.ngrok.basic_auth.credentials.authorized == false
    actions:
      - type: custom-response
        config:
          status_code: 401
          content: "Verification failed at ${time.now}"
          headers:
            content-type: text/html
            message: Basic Auth verification failed!
            endpoint_id: "${endpoint.id}"
            failed_at: "${time.now}"
  - name: successful verification response
    actions:
    - type: forward-internal
      config:
      url: https://api.internal
      binding: internal

It’s important to note that when you set enforce to false, the browser will not display a Basic Auth dialog. Instead, the browser sends the request without an Authorization header, which fails immediately—as expected. We designed this functionality with API requests in mind, as testing and debugging requests sent programmatically can be more challenging. 

What else can I do with Basic Auth?

Beyond offering powerful Basic Authentication capabilities, ngrok also allows you to inspect, replay, and analyze logged requests. 

Evaluate failed authentication events

You can view logged events in the ngrok dashboard or by examining the ngrok agent logs to gather more information about failed Basic Authentication attempts.

Migrate to the Basic Auth action

Before the release of the Basic Auth Traffic Policy action, you could configure Basic Auth using the agent CLI as follows:

ngrok http 80 --basic-auth "username1:password1" --basic-auth "username2:password2"

Transitioning from using Basic Auth on the command line to adding the Basic Auth action to your Traffic Policy rules is seamless and straightforward! To use the same Basic Auth passed on the command line in the example above with Traffic Policy, save the following to a file:

---
on_http_request:
  - name: Add basic auth
    expressions: [ ]
    actions:
      - type: basic-auth
        config:
          realm: Admin Login
          credentials:
            - ‘username1:password1’
            - ‘usermame2:password2‘

Then start your agent and pass the file as an argument:

ngrok http 80 --traffic-policy-file=/path/to/file.yml

Check it out and learn more about traffic management with ngrok

You’re all set to add the Basic Auth Traffic Policy action to your endpoints—you can sign up for a free account to get started. Here are some other resources to help you learn more about using ngrok’s Traffic Policy engine:

• CEL Interpolation docs
• Traffic Policy Engine - What are CEL variables?
• An intro to ngrok’s Traffic Policy Engine

Have questions or want to request a new feature? We’d love to hear from you. Email us at support@ngrok.com or create an issue or discussion on the ngrok community repo.