Basic Authentication

This page describes how to configure a service with HTTP authentication as Access Control Policy.

Introduction to Basic Authentication¶

Basic authentication is a authentication scheme built into the HTTP protocol. Users include an encoded string in the Authorization header of each request they make.

The string is used by the request’s recipient to verify users’ identity and rights to access a resource.

Check the MDN docs about HTTP authentication for more info.

The authentication is based on the HTTP header Authorization: Basic username:password.

The Traefik Hub Agent ensures that the HTTP header exists in the request and finds the user in its local storage. The request is forwarded to the service if the checks succeed.

Web Interface¶

You can manage your Access Control Policies from the Traefik Hub dashboard.

Traefik Hub Agent

Creating any Access Control Policy (ACP) requires you to have a connected Traefik Hub Agent. Please, refer to the installation guide for more information.

To create a BasicAuth Access Control Policy, select the Create a Policy button or go to the creation page directly.

The form contains general and method-specific fields.

Required fields¶

These fields are the required for creating an Access Control Policy.

Field	Example	Description
Name	`my-basic-auth-acp-1`	The name identifies the ACP and is used to reference this resource in other components. Must be less than 63 characters and should only contain letters, numbers, and hyphens.
Agent	`my-agent`	Refers to the agent on which the ACP will be created.
Method	Basic Auth	Authentication protocol to use in this ACP.
Users	`admin:admin` `user:password` `foo:bar`	List of users allowed to go through this ACP. The password should be in clear text and is hashed before being sent to the platform.

Additional parameters¶

These parameters allow you to configure the basic authentication deeper. They are not mandatory.

Field	Example	Description
Realm	`my-realm`	Realms allow the protected resources to be partitioned into a set of protection spaces, each with its own authentication scheme and authorization database.
Strip Authorization Header	Enabled/Disabled	Remove the `Authorization` headers from the request once authenticated.
Forward Username Header	`X-Username`	Sets the username of the requester into the given header name once authenticated.

When all the fields are set up, select the Save button to register the Access Control Policy on your cluster. The newly created ACP should be visible and manageable from the Access Control Policies listing page.

Custom Resource Definition¶

Custom Resource Definition is only available on Kubernetes.

Access Control Policies can be configured from Kubernetes manifest files containing a Traefik Hub custom resource. Custom Resource Definition contains resources that the Traefik Hub Agent can understand in order to manage ACPs.

The resource is called AccessControlPolicy from the hub.traefik.io group.

Here is the minimal working configuration to create a basic Access Control Policy.

basic-acp.yaml

apiVersion: hub.traefik.io/v1alpha1
kind: AccessControlPolicy
metadata:
  name: my-basic-auth
spec:
  basicAuth:
    users:
    # Credentials: username password
    - username:$2y$05$y8t8jU7CeZlKimCrNGfzJu3sUygiONONvksETRyfMVbQ.VVCbQMVG

Password Generation

Unlike the Traefik Hub UI, the password for a user must be hashed. Use the following command to create a username/password.

htpasswd -Bbn username password
username:$2y$05$y8t8jU7CeZlKimCrNGfzJu3sUygiONONvksETRyfMVbQ.VVCbQMVG

To create the ACP, apply the manifest on the cluster using the Kubernetes CLI tool:

kubectl apply -f basic-acp.yml

You are now able to see the ACP in the Traefik Hub UI, and in your Kubernetes cluster:

kubectl get accesscontrolpolicy my-basic-auth

References¶

Name¶

Required

metadata.name

This is the name of the resource. The name is used to reference this resource in other Kubernetes resources and is also visible in the Traefik Hub UI.

The name should have less than 63 characters. It should contain only letters, numbers, and hyphens.

Example:

metadata:
  name: my-basic-auth-1

Users¶

Required

spec.basicAuth.users

List of users allowed to go through this Access Control Policy. The password should be hashed.

Example:

spec:
  basicAuth:
    users:
    - "user1:$2y$05$5fyzwkyzKSzmxGNGhoOl1.PgmOuowj8rWlOzQ4wkpI33xBCMN7K6C"
    - "user2:$2y$05$Rj5z9WvdRHR99lxxMKfUo.bS2RyOu6Qb/3X70/X0JRmFLJa4Fl7m."

Realm¶

spec.basicAuth.realm

Realms allow the protected resources to be partitioned into a set of protection spaces, each with its own authentication scheme and authorization database.

Example:

spec:
  basicAuth:
    realm: my-realm

Strip Authorization Header¶

spec.basicAuth.stripAuthorizationHeader

Remove the Authorization headers from the request once authenticated.

Example:

spec:
  basicAuth:
    stripAuthorizationHeader: true

Forward Username Header¶

spec.basicAuth.forwardUsernameHeader

Set the username of the requester into the given header name once authenticated.

Example:

spec:
  basicAuth:
    forwardUsernameHeader: "X-Username"