From 934a1bf92276acd8041cee39196e7ca6e4efa0d5 Mon Sep 17 00:00:00 2001
From: Marlin Cremers <m.cremers@cvo-technologies.com>
Date: Jul 13 2016 21:55:47 +0000
Subject: Add guide for SAML without with Redmine


Signed-off-by: Marlin Cremers <m.cremers@cvo-technologies.com>

---

diff --git a/content/doc/example/redmine.md b/content/doc/example/redmine.md
new file mode 100644
index 0000000..b9ab172
--- /dev/null
+++ b/content/doc/example/redmine.md
@@ -0,0 +1,96 @@
+### Set up Redmine
+
+Configuring Redmine to authenticate with SAML2 enterprise authentication using Ipsilon.
+
+This guide describes how to set up Redmine to authenticate against Ipsilon as a SAML2 SP.
+
+This guide has been tested with:
+
+- Ubuntu Server 16.04
+- Ipsilon 1.2.0
+
+but is known to work with other versions.
+
+#### Install the SAML plugin
+
+Install the SAML plugin for Redmine by cloning it using Git into the `plugins` directory.
+
+`git clone git@github.com:chrodriguez/redmine_omniauth_saml.git`
+
+Install the required dependencies from the root of the installation:
+
+`bundle install`
+
+Copy assets from plugin to Redmine assets:
+
+`RAILS_ENV=production bundle exec rake redmine:plugins`
+
+Restart the Redmine instance.
+
+#### Configure Ipsilon
+
+Go to your Ipsilon web management URL, and login as an administrator account.
+Then go to **Administration -> Identity Providers -> SAML2 -> Manage, and click Add New**.
+For name you can enter anything you like, for Metadata text enter (replacing "mydomain.com" twice with your Google Apps domain name):
+
+    <?xml version="1.0"?>
+    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
+                         validUntil="2016-07-12T21:27:27Z"
+                         cacheDuration="PT1468790847S"
+                         entityID="https://redmine.cvo-technologies.com">
+        <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+            <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
+            <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+                                         Location="https://redmine.cvo-technologies.com/auth/saml/callback"
+                                         index="1" />
+        </md:SPSSODescriptor>
+    </md:EntityDescriptor>
+
+Now click Add.
+
+#### Configure Redmine
+
+Create a file in `config/initializers` called `saml.rb` with the following contents:
+
+    Redmine::OmniAuthSAML::Base.configure do |config|
+        config.saml = {
+            :assertion_consumer_service_url => "https://redmine.mydomain.com",
+            :issuer                         => "https://redmine.mydomain.com",
+            :idp_sso_target_url             => "https://ipsilon.mydomain.com/idp/saml2/SSO/Redirect",
+            :idp_cert_fingerprint           => "F7:0B:F9:.............",                                            # SSO ssl certificate fingerprint
+            :name_identifier_format         => "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
+            :signout_url                    => "http/://ipsilon.mydomain.com/idp/saml2/SLO/Redirect?ReturnTo=",
+            :idp_slo_target_url             => "https://ipsilon.mydomain.com/idp/saml2/SLO/Redirect",
+            :name_identifier_value          => "mail",
+            :attribute_mapping              => {
+                # How will we map attributes from SSO to redmine attributes
+                :login      => 'extra.raw_info.username',
+                :firstname  => 'extra.raw_info.first_name',
+                :lastname   => 'extra.raw_info.last_name',
+                :mail       => 'extra.raw_info.email'
+            }
+        }
+
+        config.on_login do |omniauth_hash, user|
+            # Implement any hook you want here
+        end
+    end
+
+Make sure to replace the hostnames and get the fingerprint from `openssl x509 -noout -in /var/lib/ipsilon/idp/saml2/idp.pem -fingerprint`.
+
+Restart the Redmine instance.
+
+#### Configure SAML plugin
+
+Go to **Administration -> Plugins -> Redmine Omniauth SAML plugin -> Configure**.
+
+Click to enable SAML authentication and change the settings to your wish
+
+#### Try it out
+
+Log out if you are logged in. Go to the login page and click on the green login button.
+You should now be forwarded to Ipsilon to log in, and afterwards sent back to Redmine, logged in.
+
+#### References
+
+* [Redmine SAML plugin](https://github.com/chrodriguez/redmine_omniauth_saml)