Overview
This document describes the configurations required for SAML 2.0 integration between the Octopus Authenticator and the Redmine service.
Integration Environment
The environment used for the integration described in this document is based on the following software versions:
- Octopus Authentication Server version 5.0.8
- Redmine version 4.2.4
Integration Workflow
Redmine integration involves the following sequential phases:
- Creating the Redmine SAML Service in the Octopus Management Console
- Configuring the Redmine SAML Integration using the Redmine Omniauth SAML plugin
Creating the Redmine SAML Service
The following procedure explains how to add a service for Redmine in the Octopus Management Console. The service settings will be used later in the Redmine SAML configuration.
To add and configure the Redmine SAML service:
1. From the Octopus Management Console, open the Services menu and click Add Service. In the Generic SAML tile, click Add.
Then, in the dialog that opens, click Create.
2. Configure the following settings in the General Info tab:
Setting | Value / Notes | |
Service Name | Enter a display name to identify the service provider (e.g., Redmine). |
|
Issuer | Enter the issuer of the service (e.g., Redmine). |
|
Description | Enter a brief note about the service, e.g., Redmine project management |
|
Display icon | This icon will be displayed on the Login page for the service. To change the default icon, click and upload the image of your choice (supported size 488x488 pixels). |
|
Login Page URL | <https://<Enterprise Base URL>/saml/<random UUID>/login> |
|
Then, click Save.
3. Open the Parameters tab, and configure the following settings:
Setting | Value / Notes |
Octopus Authenticator Login | The identifier required for the Octopus Authentication Server |
Name ID | The parameter required for Redmine login |
Method | POST |
ACS URL | http://<Redmine FQDN >/auth/saml/callback |
Audience | http://<Redmine FQDN> |
Passthrough Name ID | TRUE |
4. At the bottom of the Parameters tab, click ADD PARAMETER to create the following additional attributes to be exchanged in the SAML assertion.
The selected values can be overridden by attributes specific to a relevant directory, as described below in Step 6.
Parameter Key | Parameter Value |
username | Relevant attribute containing username, e.g., Username |
Relevant attribute containing email, e.g., Email | |
firstname | Relevant attribute containing first name, e.g., the value can be overridden by GivenName from Active Directory. |
lastname | Relevant attribute containing last name, e.g., the value can be overridden by Sn from Active Directory. |
5. Click Save.
6. Override parameter values with directory-specific attributes, as required:
a) Open the Directories tab and select the checkboxes of the directories you want to integrate with the service. Then, click Save.
b) At the top of the Parameters tab, open the Parameters list and select the relevant directory.
c) Select the checkboxes of the parameters you want to override. Then, open the list and select the attribute that will override the default value.
For example:
d) Click Save.
7. Open the Sign on tab and configure the following settings.
Keep in mind that Redmine supports SHA-1 only (not SHA-256).
Setting | Value / Notes |
Custom Message | Message shown to users on successful authentication. |
SAML Signature Algorithm | SHA-1 |
X.509 Certificate | Generate a certificate that uses the SHA-1 signature algorithm. |
8. At the bottom of the Sign on tab, click Save.
9. Open the Users tab and click Add.
A popup opens, with a list of directories displayed on the left.
10. Expand the directories list and select the checkboxes of the groups and users that you want to add to the service. Then, click Save to close the popup.
The groups and users you selected are listed in the Users tab.
11. At the bottom of the Users tab, click Save. Then, from the toolbar at the top of the page, click PUBLISH and publish your changes.
Configuring the Redmine SAML Integration
The following sections describe how to configure Redmine for integration with Secret Double Octopus, using the Redmine Omniauth SAML plugin. The integration process involves the following sequential phases:
- Setting Up the Plugin
- Editing SAML Configuration Settings
- Enabling the Plugin in Redmine
Setting Up the Plugin
Follow these steps to set up the plugin in Redmine:
1. SSH to your Redmine Server.
2. Download the Redmine Omniauth plugin and copy it to the #{RAILS_ROOT}/plugins directory. You can use git clone for this purpose, as shown in the example below.
Note that in the Secret Double Octopus lab, the #{RAILS_ROOT} directory is /opt/bitnami/redmine
3. Install the dependencies with Bundler:
4. Navigate to the #{RAILS_ROOT} directory and copy assets using the following command:
Editing SAML Configuration Settings
For successful integration, it is mandatory to configure SAML settings by adding a Ruby file to #{RAILS_ROOT} config/initializers
You may use a file name of your choice (e.g., saml.rb), but it must be a Ruby file.
Please note that a sample file named sample-saml-initializers.rb is provided in the plugin root folder. We recommend that you edit this sample file.
Before you begin, verify that you have access to the following settings from the Sign on tab of the Redmine SAML service you created in the Octopus Management Console:
- Issuer URL
- SAML 2.0 Endpoint (HTTP)
- SAML Logout URL
- X.509 Certificate Fingerprint
Configure the following settings. A sample file is shown in the figure below the table.
Setting | Value / Notes |
assertion_consumer_service_url | http://<Redmine FQDN >/auth/saml/callback |
issuer | The Issuer URL from the Redmine SAML service |
idp_sso_target_url | The SAML 2.0 Endpoint (HTTP) from the SAML service |
idp_cert_certificate | The X.509 Certificate Fingerprint from the SAML service |
name_identifier_format | Leave the default value unchanged |
signout_url | Configure as necessary, if required |
idp_slo_target_url | The SAML Logout URL from the SAML service |
name_identifier_value | Leave the default value unchanged |
attribute_mapping | Add :username => 'extra.raw_info.NameID', as shown in the example below. You can use the default values for the remaining settings. |
To commit your changes, restart your Redmine instance. (The method for this varies, depending on how you host the system.)
Enabling the Plugin in Redmine
To complete the integration process, you need to enable the plugin in your Redmine instance.
To enable the plugin:
- Log into your Redmine instance as an administrator.
- Navigate to Administration > Plugins > Configure
- Configure the settings as shown below:
4. Click Apply.
Running the Solution
This section describes the user experience of logging into Redmine via the Octopus Authenticator. The authentication process is as follows:
1. From a browser, the user navigates to Redmine, clicks Sign in and selects the relevant Login page (in this example, SDO).
2. The user enters a username and clicks Login.
The user is then redirected to the Secret Double Octopus login page.
3, The user enters a username and clicks Next.
A notification then appears on the user's Octopus Mobile App, asking for authentication approval.
4. The user taps Approve.
After successful authentication, the user is logged into Redmine.
