Basic auth

Basic authentication sends encoded user credentials in a standard header within the request. The agentgateway proxy authenticates the request against a dictionary of usernames and passwords that is stored in an AgentgatewayPolicy resource. If the credentials in the Authorization request header match the credentials in the AgentgatewayPolicy resource, the request is authenticated and forwarded to the destination. If not, the proxy returns a 401 response.

The following diagram illustrates the flow:

  sequenceDiagram
    participant C as Client / Agent
    participant AGW as Agentgateway Proxy
    participant Backend as Backend<br/>(LLM / MCP / Agent / HTTP)

    C->>AGW: POST /api<br/>(no credentials)

    AGW->>AGW: Basic auth check:<br/>No Authorization header found

    AGW-->>C: 401 Unauthorized<br/>"no basic authentication credentials found"

    Note over C,Backend: Retry with credentials

    C->>AGW: POST /api<br/>Authorization: Basic dXNlcjpwYXNzd29yZA==

    AGW->>AGW: Decode base64 → user:password
    AGW->>AGW: Lookup user in policy config
    AGW->>AGW: Verify APR1 hash<br/>(salt + hashed password)

    alt mode: Strict — Credentials valid
        AGW->>Backend: Forward request
        Backend-->>AGW: Response
        AGW-->>C: 200 OK + Response
    else Credentials invalid
        AGW-->>C: 401 Unauthorized
    end

    Note over C,Backend: Optional Mode

    rect rgb(245, 245, 255)
        Note over AGW: mode: Optional<br/>• Valid credentials → forward<br/>• Invalid credentials → 401 reject<br/>• No credentials → allow through
    end

The agentgateway proxy requires the password that the user uses to authenticate to be hashed and salted by using the APR1 format. Passwords in this format follow the following pattern: $apr1$SALT$HASHED_PASSWORD. You can use tools, such as htpasswd to generate a salt and hashed password.

Before you begin

Set up an agentgateway proxy.
Install the httpbin sample app.

Make sure that you have the following CLI tools, or something comparable:
- htpasswd to generate hashed, salted passwords.
- base64 to encode strings.

Set up basic auth

Generate a salt and hashed password for your user credentials. The following example uses the htpasswd tool for a user named user.
```
htpasswd -nbm user password
```
Example output:
```
user:$apr1$TYiryv0/$8BvzLUO9IfGPGGsPnAgSu1
```
In the example output, you can see the following information:
- Salt: TYiryv0/
- Hashed password: 8BvzLUO9IfGPGGsPnAgSu1

Create an AgentgatewayPolicy resource with your basic auth policy. The following example uses the Strict validation mode, which requires request to include a valid Authorization header to be authenticated successfully. For other common configuration examples, see Other configuration examples.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: basic-auth
  namespace: agentgateway-system
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agentgateway-proxy
  traffic:
    basicAuthentication:
      mode: Strict
      users: 
      - "user:\$apr1\$TYiryv0/\$8BvzLUO9IfGPGGsPnAgSu1"
EOF

Send a request to the httpbin app without any credentials. Verify that the request fails with a 401 HTTP response code.

curl -vi "${INGRESS_GW_ADDRESS}:80/headers" -H "host: www.example.com"

curl -vi "localhost:8080/headers" -H "host: www.example.com"

Example output:

...
< HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized

basic authentication failure: no basic authentication credentials found%   
...

Encode the expected user credentials in base64 format.
```
echo -n "user:password" | base64
```
Example output:
```
dXNlcjpwYXNzd29yZA==
```

Repeat the request. This time, you include the base64 user credentials in an Authorization header. Verify that the request now succeeds and returns.

curl -vi "${INGRESS_GW_ADDRESS}:80/headers" \
-H "host: www.example.com" \
-H "Authorization: basic dXNlcjpwYXNzd29yZA=="

curl -vi "localhost:8080/headers" \
-H "host: www.example.com" \
-H "Authorization: basic dXNlcjpwYXNzd29yZA=="

Example output:

...
* Request completely sent off
< HTTP/1.1 200 OK
HTTP/1.1 200 OK
< access-control-allow-credentials: true
access-control-allow-credentials: true
< access-control-allow-origin: *
access-control-allow-origin: *
< content-type: application/json; encoding=utf-8
content-type: application/json; encoding=utf-8
< content-length: 148
content-length: 148
< 

{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com"
    ],
    "User-Agent": [
      "curl/8.7.1"
    ]
  }
}
...

Cleanup

You can remove the resources that you created in this guide.

kubectl delete AgentgatewayPolicy basic-auth -n agentgateway-system

Other configuration examples

Review other common configuration examples.

Multiple users

Add multiple users by including additional entries in the users array.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: basic-auth
  namespace: agentgateway-system
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agentgateway-proxy
  traffic:
    basicAuthentication:
      mode: Strict
      users:
        - "admin:\$apr1\$TYiryv0/\$8BvzLUO9IfGPGGsPnAgSu1"
        - "developer:\$apr1\$abc123/\$xyz789ExampleHash"
        - "readonly:\$2y\$05\$r3J4d3VepzFkedkd/q1vI.pBYIpSqjfN0qOARV3ScUHysatnS0cL2"
EOF

Custom realm

Set a custom realm that appears in the realm name in error responses.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: basic-auth
  namespace: agentgateway-system
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agentgateway-proxy
  traffic:
    basicAuthentication:
      mode: Strict
      realm: "My Protected API"
      users:
        - "user:\$apr1\$TYiryv0/\$8BvzLUO9IfGPGGsPnAgSu1"
EOF

Optional validation mode

Use the Optional mode to validate credentials when present, but allow requests without credentials. This mode is useful for services that offer both authenticated and unauthenticated access.

⚠️

The Optional mode allows requests without credentials. Use this mode only when you intend to allow unauthenticated access to your services.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: basic-auth
  namespace: agentgateway-system
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agentgateway-proxy
  traffic:
    basicAuthentication:
      mode: Optional
      users:
        - "user:\$apr1\$TYiryv0/\$8BvzLUO9IfGPGGsPnAgSu1"
EOF

API key auth BYO ext auth service