View source for Docker Jenkins SAML Configuration

= Lingoport Docker Jenkins SAML Configuration =
<p>
This procedure describes the configuration of an Okta based SAML
Identity Provider to a an existing Docker based Jenkins Service
Provider
</p>

== Prerequisites ==
<ol>
<li>An Okta account is available and the person making the changes in
that Okta account will have Administrative rights so they can
create new Applications, Groups, and Users if needed.</li>

<li>An existing Docker based Jenkins system is already in place and is
functional for local users.</li>
</ol>

== Backup the Existing config.xml File ==

<p>
Make a backup of the config.xml file in case something occurs during
plugin install that could cause a lock out of the system by stopping
the running container, copying the XML file to a safe location and
restarting the container.
</p>

<div class="org-src-container">
  <pre class="src src-shell">
    $ sudo docker container ls
CONTAINER ID   IMAGE                       COMMAND                  CREATED         STATUS         PORTS                                                                                      NAMES
1924e0a6bf0d   jenkins/jenkins:lts-jdk11   <span style="color: #5b94ab;">"/usr/bin/tini -- /u&#8230;"</span>   2 minutes ago   Up 2 minutes   0.0.0.0:50000-&gt;50000/tcp, :::50000-&gt;50000/tcp, 0.0.0.0:8085-&gt;8080/tcp, :::8085-&gt;8080/tcp   peaceful_snyder
$ sudo docker stop 1924e0a6bf0d
$ cd /home/&lt;USER&gt;/docker/jenkins 
$ cp -p ./config.xml ./config.xml_&lt;MMDDYYYY&gt;
  </pre>
</div>

<p>
Restart the Jenkins container and confirm that it is running properly
</p>

<div class="org-src-container">
<pre class="src src-shell">$ sudo docker start 1924e0a6bf0d
$ sudo docker container ls
CONTAINER ID   IMAGE                       COMMAND                  CREATED         STATUS         PORTS                                                                                      NAMES
1924e0a6bf0d   jenkins/jenkins:lts-jdk11   <span style="color: #5b94ab;">"/usr/bin/tini -- /u&#8230;"</span>   2 minutes ago   Up 2 minutes   0.0.0.0:50000-&gt;50000/tcp, :::50000-&gt;50000/tcp, 0.0.0.0:8085-&gt;8080/tcp, :::8085-&gt;8080/tcp   peaceful_snyder
</pre>
</div>
</div>
</div>

== Install Required Plugins ==

<p>
Log into Jenkins and go to Dashboard-&gt;Manage Jenkins-&gt;Plugins-&gt;Available plugins
and search for saml
</p>

<p>
Select the checkbox under Install for the SAML plugin and for the
Role-based Authorization Strategy plugin and the select "Install" on
the upper right
</p>

<p>
Similarly search for "role" and select "Role-based Auhorization
Strategy" plugin.
</p>

<p>
Install the SAML and Role Plugins
</p>

[[File:jenkins_saml_plugin_install.png | 1200px | SAML Plugin Install]]

<p>
&lowast; Note that when this was initially installed there was an error
occurred during the SAML plugin installed, however restarting Jenkins it
showed installed so this should not be an issue if it is seen.
</p>

== Okta Configuration ==

<p>
Follow the configuration outlined in this page for configuring the
Okta system.  Once that has been completed continue on with the steps
outlined below in the Jenkins Configuration Section to configure
Jenkins to the Okta system.
</p>

[https://medium.com/globant/jenkins-secured-authentication-with-okta-saml-and-authorization-strategy-bc8408fd8d Jenkins Secured Authentication with Okta]

<p>
Here is a summary of the Okta document contents:
</p>

<ol class="org-ol">
<li>Log into the Okta Cloud instance</li>
<li>Click on Applications &rarr; Applications on the left column</li>
<li>If Jenkins is not presently added, select Browse App Catalog</li>
<li>Search for "Jenkins" and Click "Add Integration"</li>
<li>Give the installed Jenkins application a label</li>
<li>For the Base URL - you may need to have a URL that will send the
user directly to the Jenkins login page.  This may require
including the /jenkins to the end of the URL depending upon the
configuration.
<ol class="org-ol">
<li>Adding the /jenkins at the end of this configuration may be
needed if the interface gives an error when adding it
initially.</li>
</ol></li>
<li>Create a Login for a user connecting to the Jenkins system by going
to Directory &rarr; People and selecting "Add Person", filling out the
required details.</li>
<li>The user should appear in the "People" listing once added.</li>
<li>Set an Okta Group by going to Directory &rarr; Groups &rarr; Add Group and
providing a name for the Group</li>
<li>Assign the previously created user to this Group by opening up the Group just
created, select the "People Tab and select "Assign people"</li>
<li>Add the Jenkins application to the group by selecting the
Applications tab and clicking on "Assign applictions".  Select the
Jenkins application previously created.</li>
<li>Return to the Jenkins application by selecting
Applications &rarr; Applications &rarr; &lt; JENKINS LABEL &gt;</li>
<li>Select "Edit" in the Settings box to configure the SAML 2.0 items
<ol class="org-ol">
<li>Default Relay State - Leave empty</li>
<li>Disable Force Authentication - Leave checked</li>
<li>Configured SAML Attributes - Set the group to "Matches regex:.*</li>
<li>Click on "View Setup Instructions" which should open up a new
tab.  Just leave it open at this point, it will be used during
the Jenkins configuration</li>
</ol></li>
<li>In the Credential Details Section
<ol class="org-ol">
<li>Set Application username format to "Okta username"</li>
<li>Set Update application username on to "Create and update"</li>
<li>Click "Save" at the bottom to Save the configuration.</li>
</ol></li>
</ol>
</div>
</div>


== Jenkins Configuration ==

<p>
Go to Dashboard &rarr; Manage Jenkins &rarr; Security
</p>

<p>
The below will be shown
</p>

[[File:jenkins_default_security.png | 1200px | Jenkins Default Security]]


<ol class="org-ol">
<li>Set the Security Realm Pulldown to SAML 2.0</li>
<li>Copy the IDP Metatdata XML from the Guide previoulsly opened in a
separate tab during the Okta configuration to the IDP Metadata Text box.</li>
<li>Copy the IDP Metadata URL field from the Guide previoulsly opened
up in a separate tab during the Okta configuration to the IDP Metadata URL box.</li>
<li>In Display Name Attribute put "displayname"</li>
<li>In the Group Attribute put "group"</li>
<li>In the Username Attribute put "username"</li>
<li>In the Email Attribute put "email"</li>
<li>In the Username Case Conversion set the drop down to "None"</li>
<li>In Data Binding Method set the drop down to "HTTP-Redirect"</li>
<li>In the Logout URL - Copy the value from the Guide previously
opened in a separate tab during the Okta configuration.</li>
</ol>

<p>
In the Authorization Section Select "Role-Based Strategy" in the drop
down.
</p>
<ol class="org-ol">
<li>This enables the Manage and Assign Roles menu in Manage Jenkins</li>
</ol>

<p>
Click Save
</p>


<p>
Below is a screenshot of the completed SAML Configuration Screen
</p>

[[File:jenkins_saml_config_screen.png | 1200px | Jenkins SAML Configuration Screen]]


<p>
Go to Dashboard &rarr; Manage Jenkins &rarr; Manage and Assign Roles
Select Assign Roles
</p>

<ol class="org-ol">
<li>Global Roles &rarr; Add Group</li>
<li>Add Group name created in Okta (Ex. JenkinsOktaGroup) and select
Admin checkbox</li>
</ol>

<p>
Click Save
</p>

<p>
Below is a screenshot of the Jenkins Okta Group Assignment
</p>

[[File:jenkins_role_assign_okta_group.png | 1200px | Jenkins Okta Group Role Assign]]

<p>
Go to Dashboard &rarr Manage Jenkins &rarr System and scroll down to
Restrict Project Naming
</p>

<ol class="org-ol">
<li> Select the checkbox "Restrict Project Naming" </li>
<li> Select Role-Based Strategy </li>
</ol>

Click Save

Below is a screenshot of the the Restrict Project Naming configuration

<p>
Below is a screenshot of the Jenkins Role Based Assignment
</p>
[[File:project_naming_role_based_enabled.png | 1200px | Jenkins Role Based Assignment]]


== Login Validation ==

<p>
Using another browser go to the Jenkins URL.  A redirection to the
Okta Login page should occur automatically.
</p>

[[ File:jenkins_okta_login.png | 1200px | Jenkins Okta Login Screen ]]


<p>
Login using the Okta Credentials not the local Jenkins credentials
</p>

<p>
The Jenkins Dashboard should be presented.
</p>

[[ File:jenkins_dashboard_post_login.png | 1200px | Jenkins Dashboard Post Login ]]


<p>
Note that all users will be logged in with Admin level privileges
using this configuration.  It may be something that could be modified
if needed.
</p>

== Operation Validation ==

<p>
There were no changes made to the Jenkins configuration that should
impact the functionality of the Jenkins system outside of
Authentication/Authorization but a sanity check should be
performed.
</p>

<ol class="org-ol">
<li>Create a new pull request in Github.  Confirm that the build runs
on Jenkins and the comment from Globalyzer is posted to GitHub
correctly</li>
</ol>

<p>
Below is an example of a comment message from Jenkins:
</p>

[[ File:prc_commit_message_github.png | 600px | Pull Request Commit Message in GitHub ]]

== References ==

<p>
[https://medium.com/globant/jenkins-secured-authentication-with-okta-saml-and-authorization-strategy-bc8408fd8d Jenkins Secured Authentication with Okta]
</p>

<p>
[https://www.okta.com/integrations/jenkins/#capabilities Okta Certification of SAML Plugin]
</p>

<p>
[https://plugins.jenkins.io/saml/ SAML Plugin Page]
</p>

<p>
[https://plugins.jenkins.io/role-strategy/ Role-based Authorization Strategy Plugin Page]
</p>