This article describes how to setup Velocity as a Service Provider (SP) using Okta as a SAML 2.0 Identity Provider (IdP) for authentication. Please contact us to enable this functionality before beginning the setup process.

To configure your organization to use SAML for authentication, you will need administrator permissions within Velocity and your IdP.

Helpful links for setting an application on Okta:

Okta: Create your Integration

Velocity uses the following format for its Assertion Consumer Service (ACS) URLs:

https://velocity.codeclimate.com/org/:organization

Navigate to the SAML Settings page and choose a unique organization identifier which will form the last part of your ACS URL. You can use your organization name or something else, as long as it is unique.

Navigate to configure SAML tab of your app, and use these settings:

Velocity needs metadata about your IdP in order to successfully communicate with it using SAML. There are two options for this:

If both options are available, the URL is preferable, as it allows for the IdP to update metadata without your intervention.

You can find Idp metadata under the Sign On tab. Copy the IdP Metadata URL to your clipboard, or download the IdP Metadata XML file and copy the entire contents of the file to your clipboard for Step 5. Note: Copying the XML directly from the Okta settings can result in misformatted XML. To avoid this, we recommend using Save Link As to save the XML as a text file, locally. Then, copy the XML from your text editor and paste into the Velocity settings page.

Velocity is able to use names and email addresses from your IdP when provisioning users. Setup metadata mappings for the following fields (note these are case sensitive):

In order to successfully provision users through SAML, we need to define Velocity roles. When a user logs in to Velocity using SAML, if we don’t have their record, we can auto-provision them with a role that is specified in your SAML settings in Velocity (Option 1). Alternately, we can auto-provision them with a role that's defined in Okta (Option 2).

Option 1: Configure roles in Velocity:

You can set an auto provision role in Velocity here. By selecting Manage roles within Velocity each auto provisioned user will be assigned the role selected in the dropdown.

5.1.1. Navigate to your applications User Profile Mappings by clicking Directory -> Profile Editor and Edit your organization’s User Profile

5.1.2: Under the Profile section, create a new attribute. This custom attribute will be used to assign roles to Velocity Users.

Note: Variable name is going to be a key for defining all your mappings. You will need to use that variable name later when defining an xml attribute for role. The naming is case sensitive.

5.1.3. Add mappings to the new custom attribute:

Afterwards, save changes by clicking Apply updates at the bottom of the mapping modal.

You can think of those mappings as Okta having 2 tables or objects: one for Okta, and one for Application. The Applications “appuser” object has RoleInVelocity key, and Okta has “user” object that has role key. You must create mappings for each object in order for them to communicate successfully.

Click Save Mappings and select Apply updates now so that the new mappings apply to all users with this profile.

At this point, when you assign your application to people, you should see each User having a RoleInVelocity field:

In this field, you can define a role that you want your particular user to have in Velocity. Note: You must assign a role that exists in your Velocity’s organization in order to successfully auto provision users.

5.1.4 Add role attribute to XML

At this point, you can define an attribute that will be sent to your SP with the role you've defined. Make sure the attribute specified in Okta matches the Role key specified in Velocity’s SAML config.

Adding roles from Okta groups:

So far, we’ve discussed how to set roles on individual users in Okta. However, this is very inconvenient. You can optimize role assignment by specifying groups in Okta.

Each Group will have a specified role key, and will have assigned users.

1. Navigate to Groups settings by going to Directory → Groups.

2. Choose the Add Group option at the top section of the Group list, which will render this modal. You can name this group anything you want.

3. Once a new group is created, you can assign applications to group by navigation to the Manage Apps option. When you choose to assign this group to the application, it will prompt you to assign this group a Role attribute. You can assign any role that you want this group to be associated with, as long as this role exists in your organization in Velocity. Also note, that naming is case sensitive.

4. After assigning apps to the group, you are able to assign users. Choose the Manage People option and assign users that you want to be associated with this role.

5. After assigning users to the group, you need to update your applications assignment. Navigate to the Assignments tab for your app. In the following example, we have individual assignments for all users. Follow steps in this Okta doc to assign users to groups.
​

Return to the SAML Settings within Velocity and paste the XML from Okta into the Identify Provider (IdP) XML Metadata field and save. You can find XML file by going into your application’s general settings and Editing SAML settings. In the configure SAML step, at the bottom of the section, you will see the “Preview the SAML assertion” option, which will provide you with the XML file you need to paste in Velocity SAML settings.

Finally, you'll need to Verify your SAML config. If the verification is successful, you can activate SAML authentication in Velocity.

Now that you’ve validated you can authenticate with SAML via your IdP, you can enforce the requirement that all users within your Velocity organization sign in this way.

New users must be invited to your Velocity organization, and they will need to authenticate via SAML to accept their invitations.

Please contact us and we can enable this setting on your Velocity organization.