RedmineX Microsoft Entra Auth

The RedmineX Microsoft Entra Authentication plugin allows users to sign in to Redmine using their Microsoft Entra ID account.
Detailed setup guide: The plugin package contains a comprehensive README.md with step-by-step Microsoft Entra configuration, screenshots, permissions, OAuth setup and troubleshooting.
Please follow the README when installing and configuring the plugin. This page covers the most important requirements, existing-user migration and common problems you may encounter.

1. Go To Root & Unzip

Unzip the archive and upload the folder redmine_x_microsoft_auth to redmine_root/plugins or upload the archive in the same location and perform the unzip command in the console. Do NOT change the plugin folder name.

2. Install Gems

From redmine_root run bundle install. No need for any migration (rake).

If the gems were installed correctly, this is roughly what you should see.

3. Migrate

When installing RedmineX Microsoft Entra Auth plugin, you need to run the migration command bundle exec rake redmine:plugins:migrate RAILS_ENV=production.

If the migration went well, this is roughly what you should see.

4. Restart

Restart Redmine. Based on your hosting provider / web server, you will need to run the following commands. Puma: sudo systemctl restart redmine.yourcompany.com.service or Passenger: touch tmp/restart.txt.

5. For Redmine 6.x+ Only

If you are using Redmine 6+, make sure you have pre-compiled all assets.

1. Ensure correct permissions: chmod -R 755 redmine_root/public/plugin_assets

2. Clear cache: rm -rf tmp/cache

3. Precompile assets (if you're in production mode): bundle exec rake assets:precompile RAILS_ENV=production

4. Restart Redmine

1. Go To Root & Unzip

Remove the redmine_x_microsoft_auth and upload the unziped folder of the new version. Alternatively, you can copy the archive in the same location and perform the unzip command in the console.

2. Install Gems

From redmine_root run bundle install. No need for any migration (rake).

3. Restart

Restart Redmine. Based on your hosting provider / web server, you will need to run the following commands. Puma: sudo systemctl restart redmine.yourcompany.com.service or Passenger: touch tmp/restart.txt.

The RedmineX Microsoft Entra Authentication plugin allows users to sign in to Redmine using their Microsoft Entra ID account.

Detailed setup guide: The plugin package contains a comprehensive README.md with step-by-step Microsoft Entra configuration, screenshots, permissions, OAuth setup and troubleshooting.

Please follow the README when installing and configuring the plugin. This page covers the most important requirements, existing-user migration and common problems you may encounter.

Before you start

To configure Microsoft Entra authentication, you will need to register your Redmine installation as an application in Microsoft Entra ID.

The plugin requires the following values:

• Application (Client) ID

• Directory (Tenant) ID

• Client Secret VALUE — not the Secret ID

The detailed README.md included with the plugin explains how to create the Entra application, configure the redirect URI, add the required Microsoft Graph permissions, grant Admin Consent and retrieve these credentials.

Configure the RedmineX plugin

In Redmine, go to:

Administration → Plugins → Microsoft Auth → Configure

Enter your:

• Client ID

• Client Secret

• Tenant ID

Enable OAuth authentication and apply the configuration.

Existing Redmine users

The plugin matches Microsoft Entra users with existing Redmine users by email address.
This is particularly important when migrating an existing Redmine installation from LDAP, another authentication method or an old Microsoft domain.
If the user's email address is changing during the migration, update the email address of the existing Redmine account before enabling Entra authentication.

Example

Existing Redmine user:

• User ID: 42

• Login: oldusername

• Email: user@old-domain.com

New Microsoft Entra account:

• UPN: firstname.lastname@new-domain.com

• Email: firstname.lastname@new-domain.com

Change the existing Redmine user's email address to firstname.lastname@new-domain.com.

When the user signs in through Microsoft Entra, the plugin will match the Entra identity with the existing Redmine account.

The original Redmine user ID remains unchanged, so existing issues, assignments, project memberships, time entries and history remain associated with the same user.

There is no need to manually map Microsoft Entra Object IDs to Redmine user IDs.

Important: Update and verify email addresses before allowing existing users to sign in through Microsoft Entra and test on a stagong environment. 

If the email address returned by Microsoft does not match an existing Redmine account, a new Redmine account will be created. This can result in duplicate users while historical data remains associated with the original account.

For larger migrations, we recommend testing the process with a small number of users before enabling Entra authentication for the entire organization.

Troubleshooting

I don't see the "Continue with Microsoft" button

First, verify that the Microsoft Entra application and plugin are configured correctly, including:

• Client ID

• Tenant ID

• Client Secret

• OAuth settings

• Redirect URI

Refer to the detailed README.md included with the plugin to verify the complete Microsoft Entra configuration.

If the configuration is correct, another Redmine plugin or customization may be overriding the login page and preventing the Microsoft login button from being displayed.

Test for a plugin conflict

1. Create a folder named _NOTUSED inside your Redmine /plugins directory.

2. Move all plugins except the Microsoft Entra Authentication plugin into /plugins/_NOTUSED.

3. Restart Redmine.

4. Open the Redmine login page again.

If Continue with Microsoft now appears, another plugin is causing the conflict.

Move the other plugins back into /plugins one by one, restarting Redmine as necessary and checking the login page after each plugin is restored.

The plugin after whose return the Continue with Microsoft button disappears is the likely source of the conflict.

The Microsoft button exists but is not visible

If the Microsoft login button exists in the HTML source but is not visible on the page, the OAuth integration is likely initialized correctly and the problem is more likely caused by:

• CSS overrides

• UX/UI customization

• Another frontend plugin

Temporarily disabling UX or frontend customization plugins using the _NOTUSED procedure above can help identify the conflict.

A duplicate Redmine user was created

Check the user's email address.

The email address of the existing Redmine user must match the email address returned by Microsoft Entra.

For existing installations, update and verify users' email addresses before allowing them to authenticate through Microsoft Entra.

Authentication stopped working after changing the Redmine URL

Microsoft Entra is configured with redirect URLs for your Redmine installation. If your Redmine domain or URL changes, review the application configuration in Microsoft Entra and update the redirect URI accordingly.

Quick checklist

• Microsoft Entra application is registered

• Client ID is correct

• Tenant ID is correct

• Client Secret VALUE is used, not the Secret ID

• Required Microsoft Graph permissions are configured

• Admin Consent is granted where required

• Redirect URI is correct

• OAuth authentication is enabled in the plugin

• Redmine Self-registration is set to Automatic account activation

• Existing Redmine email addresses match Microsoft Entra email addresses

• The Continue with Microsoft button is visible

Detailed installation and Microsoft Entra configuration

This documentation intentionally focuses on the requirements and problems most commonly encountered when using the plugin.

For the complete installation procedure, Microsoft Entra application registration, API permissions, Admin Consent, redirect URI configuration, screenshots, end-to-end login testing and additional troubleshooting, please refer to the README.md included with the Microsoft Entra Authentication plugin package.