About basic auth

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

Gloo Gateway 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.

To set up basic auth, you use the following Gloo Gateway APIs:

  • AuthConfig: Set up the basic dictionary of usernames and passwords that you want to allow.
  • RouteOption: Add the AuthConfig to a route configuration. You can then reference the RouteOption resource in an HTTPRoute by using the ExtensionRef filter to configure the route for basic auth.

Before you begin

  1. Follow the Get started guide to install Gloo Gateway, set up a gateway resource, and deploy the httpbin sample app.

  2. Get the external address of the gateway and save it in an environment variable.

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n gloo-system gloo-proxy-http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS
    kubectl port-forward deployment/gloo-proxy-http -n gloo-system 8080:8080

Setup

  1. 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

  2. Retrieve the salt and hashed password from the output of the previous step.

    • Salt: TYiryv0/
    • Hashed password: 8BvzLUO9IfGPGGsPnAgSu1

  3. Create an AuthConfig resource and add your external authentication rules. The following example configures basic authentication for the user user by using the hashed password and salt that you created earlier.

    kubectl apply -f- <<EOF
apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: basic-auth
  namespace: httpbin
spec:
  configs:
    - basicAuth:
        apr:
          users:
            user:
              hashedPassword: 8BvzLUO9IfGPGGsPnAgSu1
              salt: TYiryv0/
        realm: gloo
EOF

  4. Create a RouteOption resource and reference the AuthConfig resource that you just created.

    kubectl apply -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: RouteOption
metadata:
  name: basic-auth
  namespace: httpbin
spec:
  options:
    extauth:
      configRef:
        name: basic-auth
        namespace: httpbin
EOF

  5. Create an HTTPRoute resource for the httpbin app that requires authentication for requests on the extauth.example domain.

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-basic-auth
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: gloo-system
  hostnames:
    - extauth.example
  rules:
    - filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.solo.io
            kind: RouteOption
            name: basic-auth
      backendRefs:
        - name: httpbin
          port: 8000
EOF

  6. Send a request to the httpbin app on the extauth.example domain. Verify that your request is denied and that you get back a 401 HTTP response code.

    curl -v http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: extauth.example:8080"
    curl -v localhost:8080/status/200 -H "host: extauth.example"

    Example output:

    * Mark bundle as not supporting multiuse
< HTTP/1.1 401 Unauthorized
< www-authenticate: Basic realm="gloo"
< date: Fri, 19 Apr 2024 17:41:01 GMT
< server: envoy
< content-length: 0

  7. Encode the expected user credentials in base64 format.

    echo -n "user:password" | base64

    Example output:

    dXNlcjpwYXNzd29yZA==

  8. Send another request to the httpbin app. This time, you include the base64-encoded user:password credentials in the Authorization header. Verify that the request succeeds and that you get back a 200 HTTP response code.

    curl -v http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: extauth.example:8080" -H "Authorization: basic dXNlcjpwYXNzd29yZA=="
    curl -v localhost:8080/status/200 -H "host: extauth.example" -H "Authorization: basic dXNlcjpwYXNzd29yZA=="

    Example output:

    * Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< access-control-allow-credentials: true
< access-control-allow-origin: *
< date: Fri, 19 Apr 2024 17:44:06 GMT
< content-length: 0
< x-envoy-upstream-service-time: 0
< server: envoy

Cleanup

You can optionally remove the resources that you set up as part of this guide.
kubectl delete authconfig basic-auth -n httpbin
kubectl delete routeoption basic-auth -n httpbin
kubectl delete httproute httpbin-basic-auth -n httpbin