SAML Installation Instructions

This guide will walk you through all the steps to install the SAML addon.

To install the add-on:

1. First get the addon from the portal. You can view all the available addons for your plan here: https://portal.securityroots.com/addons.
2. Then, unpack the zip file. It should contain some .gem files and a Gemfile.plugins file that you'll need for the installation.
3. SSH into the box as dradispro
4. Copy the .gem files to /opt/dradispro/dradispro/shared/addons/cache/ (create the directory if it doesn’t exist)
5. Copy the .yml files (if any) to /opt/dradispro/dradispro/shared/addons/config/
6. Copy the .rb files (if any) to /opt/dradispro/dradispro/shared/addons/initializers/
7. Append the contents of the Gemfile.plugins file to the Gemfile.plugins under /opt/dradispro/dradispro/current
8. Symlink files:

   $ cd /opt/dradispro/dradispro/current/vendor/cache/
   $ ln -s /opt/dradispro/dradispro/shared/addons/cache/*.gem ./

9. If you copied over .yml files to /opt/dradispro/dradispro/shared/addons/config/, run the following:

   $ cd /opt/dradispro/dradispro/current/config/
   $ ln -s /opt/dradispro/dradispro/shared/addons/config/*.yml ./

10. If you copied over .rb files to /opt/dradispro/dradispro/shared/addons/initializers/, run the following:

    $ cd /opt/dradispro/dradispro/current/config/initializers/
    $ ln -s /opt/dradispro/dradispro/shared/addons/initializers/*.rb ./

11. Install the plugins and compile:

    $ cd /opt/dradispro/dradispro/current/
    $ RAILS_ENV=production bundle install --local --without development test
    $ RAILS_ENV=production ./bin/rails assets:precompile

12. $ RAILS_ENV=production ./bin/rails g dradis:pro:plugins:saml:install

13. Enter credentials for your Identity Provider and other settings. You will need:
1. The public certificate
2. The fingerprint algorithm
3. Possibly you may need to generate the fingerprint, if the Identity Provider (such as PingIdentity or SecureAuth) does not display or create one.
14. Follow last readme steps provided by the plugin installer
15. Re-start the app process:

    $ god restart

Confirm that the installation has completed by visiting the login page and seeing a "Sign in with {{provider}}" button. If you click the sign in button and receive any errors there may be more information about the specific setup problem in the logs.

Upgrading your SAML plugin

You should be able to upgrade your SAML plugin following the installation steps from above. However, if you are upgrading to v4.3 of the SAML plugin from an earlier version, then some changes will be required in your /opt/dradispro/dradispro/current/config.saml.yml file.

1. Change idp_sso_target_url to idp_sso_service_url
2. Add: email_attribute: name_id

As of v4.3 of Dradis, your /opt/dradispro/dradispro/current/config.saml.yml file should look something like this:

production:
  admin_group_id: admin
  assertion_consumer_service_url: https://[your Dradis IP]/pro/auth/saml/consume
  email_attribute: name_id
  idp_cert_fingerprint: [redacted]
  idp_cert_fingerprint_algorithm: http://www.w3.org/2000/09/xmldsig#sha1
  idp_provider: OneLogin
  idp_sso_service_url: https://[redacted].onelogin.com/trust/saml2/http-post/sso/[redacted]
  issuer: dradispro
  name_attribute: Name
  name_identifier_format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

That should get you up and running with the SAML addon. If you're running into issues, please contact our support team and let us know!