Skip to content

Basic Authentication

Basic authentication is the simplest method to protect your service. It consists of a list of hard-coded users allowed to reach the service.

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

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, click on the Create a Policy button at the top-right corner of the page or go to the creation page directly.

Create ACP

Create BasicAuth

The form contains general and method-specific fields.

Required

These are the required fields 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/or 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, click 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.

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

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

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/or 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"