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.

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/v1beta1
    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.

    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.

    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