Kanboard Documentation

Reverse Proxy Authentication

This authentication method is often used for SSO (Single Sign-On) especially for large organizations.

The authentication is done by another system, Kanboard doesn’t know your password and suppose you are already authenticated.

Requirements

Apache Auth on the same server or a well-configured reverse proxy.

How does this work?

  1. Your reverse proxy authenticates the user and send the username through a HTTP header.
  2. Kanboard retrieve the username from the request
    • The user is created automatically if necessary
    • Open a new Kanboard session without any prompt assuming it’s valid

Installation instructions

Setting up your reverse proxy

This is not in the scope of this documentation. You should check the user login is sent by the reverse proxy using a HTTP header, and find out which one.

Setting up Kanboard

Create a custom config.php file or copy the config.default.php file:

<?php

// Enable/disable reverse proxy authentication
define('REVERSE_PROXY_AUTH', true); // Set this value to true

// The HTTP header to retrieve. If not specified, REMOTE_USER is the default
define('REVERSE_PROXY_USER_HEADER', 'REMOTE_USER');

// The default Kanboard admin for your organization.
// Since everything should be filtered by the reverse proxy,
// you should want to have a bootstrap admin user.
define('REVERSE_PROXY_DEFAULT_ADMIN', 'myadmin');

// The default domain to assume for the email address.
// In case the username is not an email address, it
// will be updated automatically as USER@mydomain.com
define('REVERSE_PROXY_DEFAULT_DOMAIN', 'mydomain.com');

// Header name to use for the user email (optional)
define('REVERSE_PROXY_EMAIL_HEADER', 'REMOTE_EMAIL');

// Header name to use for the user full name (optional)
define('REVERSE_PROXY_FULLNAME_HEADER', 'REMOTE_NAME');
  • If the proxy is the same web server that runs Kanboard, according the CGI protocol the header name will be REMOTE_USER. For example, Apache add REMOTE_USER by default if Require valid-user is set.
  • If you use a different header for REVERSE_PROXY_USER_HEADER, the value must be prefixed by HTTP_, all hyphens must be replaced by underscores, and the string must be in all capitals, because it's fetched from the $_SERVER array. For example, X-Proxy-Username becomes HTTP_X_PROXY_USERNAME.
  • If Apache is a reverse proxy to another Apache running Kanboard, the header REMOTE_USER is not set (same behavior with IIS and Nginx).
  • If you have a real reverse proxy, the HTTP ICAP draft proposes the header to be X-Authenticated-User. This de facto standard has been adopted by a number of tools.