Okta Installation Instructions

This guide will walk you through all the steps to install the Okta Addon.

Setup an application in Okta

Before you get started, you will need to setup an application in Okta.

1. In the sidebar, go to Applications > Applications and create a new App Integration.
2. Select "OpenID Connect" and then "Web Application" and click "Next".
3. Give the application a recognizable name and under the "Login Redirect URIs" section, add this url "[https://yourdomain.com]/pro/auth/okta/callback" but replace [https://yourdomain.com] with your Dradis Pro web url.
4. In Assignments > Controlled Access, select "Allow everyone in your organization to access" or select a group if you have one already.
5. Click "Done".

If you want to automatically assign users as an Admin when signing in to your Dradis Pro application, you will need to create groups (if you don't have one to identify admins) and configure Oauth2 scopes.

1. In Okta, click on Directory > Groups in the sidebar.
2. Add a group and give it a name. Take note of the exact spelling of the group's name, and click "Add Group".
3. Next, click on Security > API in the sidebar.
4. Click on the "default" authorization server.
5. Click on "Scopes" tab and add a new Scope.
6. Enter "groups" for the scope name, uncheck "Set as a default scope" and check "Include in public metadata". Click "Create"
7. Now go to "Claims" tab, and add a new claim.
8. Enter "groups' for the name, select "Groups" for the Value type, and select "Equals" for the filter and enter your group name that you created earlier.
9. Under "Include in" section, select "The following scopes", and enter "groups" in the input field. Wait for the "groups" option to populate and select it. Click "Create".

You will need to tweak the okta.yml file to match your credentials:

production:
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  issuer: "your-client-issuer"
  admin_group_name: "your-admin-group-name"

You can get your your client_id and client_secret under Applications > Your okta application > General, and scroll to the bottom.

You can get your issuer under the API tab.

Your admin_group_name is the group name that was created in Okta.

Installation instructions for the Okta addon in Dradis

Now you'll need to run some commands on the Dradis instance to install the Okta plugin.

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. Re-start the app process:

$ god restart

That should get you up and running with the Okta addon. When you go to log into the Dradis web application, there should now be a "Log in with Okta" button present. If you're running into issues, please contact our support team and let us know!