Authentication

Configure local authentication, LDAP, OAuth2, and two-factor authentication in Redmine.

Redmine supports multiple authentication methods that can be combined to meet your security requirements.

Local authentication

Local authentication stores user credentials in the Redmine database using bcrypt password hashing. It is enabled by default and requires no additional configuration.

Key settings for local authentication are managed at Administration → Settings → Authentication:

Setting	Description
login_required	Require login to access any part of the application.
self_registration	Control how new users register: disabled, email activation, automatic, or manual approval.
lost_password	Allow users to reset their password via a link sent to their registered email address.
password_min_length	Enforce a minimum password length (default: 8 characters).
password_max_age	Force password changes after a set number of days. Set to 0 to disable expiry.
password_required_char_classes	Require passwords to contain uppercase letters, lowercase letters, digits, and/or special characters.
session_lifetime	Maximum total duration of a user session in minutes.
session_timeout	Idle session timeout in minutes.
autologin	Duration in days for the “remember me” autologin cookie. Set to 0 to disable.

LDAP

Redmine can authenticate users against one or more LDAP (or Active Directory) servers. LDAP authentication sources are managed at Administration → LDAP authentication.

See LDAP configuration for detailed field descriptions, configuration examples, and on-the-fly user creation.

The net-ldap gem is required for LDAP authentication. It is included in the :ldap Gemfile group and installed with:

bundle install --without development test

OAuth2 (Doorkeeper)

Redmine includes Doorkeeper (~> 5.8.2) to act as an OAuth2 authorization server. This allows third-party applications to authenticate with Redmine and access the REST API on behalf of users.

OAuth2 applications are managed at Administration → OAuth applications.

Registering an application

1. Go to Administration → OAuth applications → New application.
2. Enter the application name and redirect URI.
3. Select the scopes the application may request.
4. Save to receive a client ID and client secret.

Authorization flows

Doorkeeper supports the standard OAuth2 authorization code flow:

1. The client redirects the user to /oauth/authorize with the client_id, redirect_uri, response_type=code, and requested scope.
2. The user approves the request.
3. Redmine redirects back to the client with a code parameter.
4. The client exchanges the code for an access token at /oauth/token.
5. The client uses the token in the Authorization: Bearer <token> header for API requests.

Two-factor authentication

Redmine supports TOTP-based two-factor authentication using the rotp gem (>= 5.0.0) and rqrcode for QR code generation.

Enabling 2FA

The twofa setting at Administration → Settings → Authentication controls the policy:

Value	Behavior
0	Two-factor authentication is disabled for all users.
1	Two-factor authentication is optional. Users may enroll voluntarily.
2	Two-factor authentication is required for all users.
3	Two-factor authentication is required for administrators only.

Switching from any enabled state to 0 (disabled) automatically unpairs all existing 2FA enrollments. This action cannot be undone.

User enrollment

When 2FA is optional or required, users enroll from their My account page:

1. Navigate to My account → Two-factor authentication.
2. Scan the QR code with a TOTP-compatible authenticator app (e.g. Google Authenticator, Authy).
3. Enter the 6-digit code to confirm pairing.
4. Store the provided backup codes in a safe location.

Backup codes

During enrollment, Redmine generates a set of single-use backup codes. Users should store these codes securely. Each backup code can be used once in place of a TOTP code if access to the authenticator app is lost.

Sensitive data encryption

TOTP secret keys are stored encrypted in the database. Configure the encryption key in config/configuration.yml:

config/configuration.yml

default:
  database_cipher_key: "your-long-random-secret-key"

Losing or changing database_cipher_key makes all encrypted data (TOTP secrets, LDAP passwords, SCM passwords) unreadable. Store this key securely and do not change it after initial setup.

To encrypt existing data after setting the key:

bundle exec rake db:encrypt RAILS_ENV=production