Jenkins secured authentication with OKTA, SAML, and Authorization strategy.

Published in

Globant

6 min readNov 9, 2021

Most IT/Cloud engineers' concerns are security-related when it comes to accessing either public or private applications. therefore, the authentication process must be as safe as possible. Now, when we talk about CI/CD especially Jenkins, we can explore a secured login method and service available in the market.

Here, we are going to go through every step related to securely logging into Jenkins using Okta.

What is OKTA?

Okta is a platform designed to comply with secured authentication protocols as well as SSO features, it helps organizations, customers, and clients by helping them integrate existing directories such as AWS, Azure, GCP, Slack, and others to provide a consistent single sign-on experience.

Recipe

An Okta account.
A Jenkins instance.
Jenkins SAML Plugin installed.
Jenkins Role-based Authorization Strategy plugin installed.

Steps:

At OKTA

Go to your organization’s admin dashboard URL https://your-organization.okta.com/admin/dashboard.

From the left menu, select Applications, from the center screen click on the Browseapp catalog button and type Jenkins in the search box. There you can add the Jenkins application.

2. Set OKTA application:

In application Label: Provide a friendly name convention for your Jenkins.

In Base URL: Provide your HTTPS Jenkins URL https://my-organization.my-domain.com:8888.

Note: Although OKTA allows you to set an HTTP protocol this is not recommended. If you need to configure SSL in your Jenkins instance, refer to the following guides (ref1, ref2).

If you want to configure a self-managed SSL service in AWS you can refer to the following guide for EC2 Instances:

Configure ACM certificates for Websites hosted on EC2

3. Set OKTA Group:

From the left menu, select Directory, Groups, then click the add group button in the center of the screen.

Select your group and then click on the Manage people button. In there, add the individuals you want to have access to your Jenkins installation and then click the Save button.

4. Set OKTA Application:

From the left menu, select Applications, Applications, then click the Jenkins Applications. Then, click on the Sign On tab, and click on the Edit highlighted text.

Configure the SAML 2.0 attributes:

In Default Relay State: Leave it empty.

In Disable Force Authentication: Leave it by default (checked)

In Configured SAML Attributes:

Group: Select Matches regex and add the pattern .*

Click on the View setups Instructions button this will open the OKTA guide in a new Tab, leave it open since the values generated in there will be needed in a further step.

In Credentials Details:
In Application username format: Okta username
In Update application username on: Create and update

Scroll down to the bottom and click the save button.

At Jenkins

Relevant notes:

Before doing any modifications to your SAML module it is strongly recommended to back up your Jenkins’ config.xml file. In most Linux distributions this file can be found in the following path:

/var/lib/jenkins/config.xml

Rolling-Back

In case things do not go as anticipated, restore your backed-up config.xml file and restart your Jenkins installation. Also, make sure the config.xml file has the proper permission as seen next:

-rw-r--r-- 1 jenkins jenkins Nov 5 16:20 /var/lib/jenkins/config.xml

Unlocking your Jenkins Instance

In case you accidentally forgot to back up the Jenkins’ config.xml file and therefore you find locked out from the Jenkins installation. You can restore access by executing the following line in the ssh console:

sed -i 's/<useSecurity>true<\/useSecurity>/<useSecurity>false<\/useSecurity>/g' /var/lib/jenkins/config.xml

Make sure you isolate Jenkins access exclusively to you before executing this line since this command will disable global authentication in Jenkins, anyone with your installation URL would enter with admin privileges.

After executing the above command proceed to restart your Jenkins installation for these changes to take effect. Then, go to your admin panel and set security back again, it’s worth saying that this procedure should be applied as a last resort.

Go to Manage Jenkins > Configure Global Security:

Go back to the tab opened in the previous Step View Setup Instructions. Scroll down to the IdP Metadata in the guide and copy its values and paste the information to your Jenkins SAML 2.0 IdP metadata field:

Repeat the Same for the procedure by copying the values from IdP Metadata URL field in the guide and pasting it into your Jenkins IdP Metadata URL field.

In Display Name Attribute: displayname

In Group Attribute: group

In Username Attribute: username

in Email Attribute: email

In Username Case Conversion: None

In Data Binding Method: HTTP-Redirect

In Logout URL: Copy and paste the value from the OKTA Guide.

2. Go to Manage Jenkins > Manage and Assign Roles >
Assign Roles:

In User/group to add: type the okta group (oktagroup), created in previous. then click the ADD button:

In the Global Roles table: Check admin role. Then click the SAVE button.

Note: Here the oktagroup was granted with the existing admin role privilege for testing purposes, however, you must set individual roles to comply with your organization's needs. Refer to the role-based authorization strategy plugin guide for further details.

Log-off and log-in back into your Jenkins installation.

Validate Access

Log back to your Jenkins URL. Redirection to your OKTA organization will take place:

Once the OKTA authentication takes place, you will be redirected back to Jenkins with the user SSO authentication already approved with access granted to the instance.

Let’s check on our user at Jenkins Side

Conclusions:

Secured access from OKTA SAML 2.0 towards Jenkins is fairly easy to set.
Groups in OKTA can be easily matched against Jenkins Instance Groups.
The Role-Based Authorization strategy plugin works as expected with OKTA integration.
HTTPS protocol on the Jenkins side is strongly needed to comply with secured communication.