SAML — Secure Assertion Markup Language is used for federated authentication; when a service that we need to get access to (a Service Provider), asks another service (an Identity Provider) to perform a user’s authentication.

Check the documentation here>>>.

Service Provider ( SP ): is a system that needs to authenticate, in our case this will be Jenkins

): is a system that needs to authenticate, in our case this will be Jenkins Identity Provider (IDP): is a system where users are stored and will perform exactly authentication steps, in our case this will be Okta

Their communication and steps during authentication can be displayed in the next scheme:

Here:

SAML Request: or authentication request, created by an SP to request a user’s authentication

SAML Response: will be created by an IDP and contains data about an already authenticated user, and may include some additional information like user’s groups and so on

Also, keep in mind that SAML-authentication can be two types:

A Service Provider Initiated (SP-initiated): a service, Jenkins in this case, performs initialization to an IDP provider when a user tries to log in to the Jenkins instance

An Identity Provider Initiated (IDP-initiated): and vise versa — when Okta’s user will click on a button to log in to the Jenkins — IDP will initialize a request to the Jenkins (SP) to authenticate this user

This post mostly will speak about Service Provider Initiated, but still, Identity Provider Initiated will work as well.

Also, keep in mind that an SP and an IDP will never talk directly to each other — a user’s browser will act like a “proxy” between them.

A Service Provider role

An IDP generates a SAML response for an SP and then SP has to check if this response was received from a valid IDP and then parse this response to get necessary data — a user’s name, groups, and other attributes.

To do so, an SP needs to obtain the next information from an IDP:

an IDP’s public certificate

ACS Endpoint (Assertion Consumer Service URL) or just “SP login URL” — an endpoint URL passed by an SP to an IDP to receive SAML replies

IDP Login URL — an IDP’s endpoint where SP will send its SAML requests

Jenkins SAML for Okta

The main goal in the SAML integration to the Jenkins is:

store users in Okta

Okta’s users are grouped to groups

Jenkins will use a Role-Based Strategy plugin that will have access roles assigned to various groups

In Okta Jenkins SAML can be configured in two ways:

by using a native Okta’s application — less work for configuration, but has no ability to pass user’s groups to Jenkins, will be covered in the Okta Community Created Jenkins SAML application part of this post or by creating an own SAML-based application in Okta which will have a custom attribute with user group field, will be covered in the Okta and our application for Jenkins SAML part of this post

With the first way, you’ll be unable to use the Role-Based Strategy plugin but still can use a Matrix-based security or Matrix Authorization Strategy plugins:

The Role-Based plugin configuration will be described in the following parts and now in the post will see how to configure Okta and SAML for Jenkins in both ways mentioned above.

Okta native Jenkins SAML application

Okta configuration

Go to the Okta > Add app, find a Jenkins SAML plugin:

Set a Jenkins’ URL:

Switch to the Sign On tab:

Click on the View Setup Instructions — Okta already has all data generated here to be used by our SP (Jenkins):

Go to the Assignment tab and add the Jenkins SAML app to desired Okta’s users:

Navigate to your Jenkins.

SAML configuration in Jenkins

Install the SAML plugin:

Go to the Configure Global Security, switch your authentication realm from the Jenkins’ own user database to the SAML:

Go back to Okta and the metadata page, copy the IDP Metadata content:

Paste to the Jenkins’ SAML settings:

Return to your Okta, copy link to the Identity Provider metadata:

Set it in Jenkins to the IDP Metadata URL field:

Display Name Attribute and Group Attribute leave as is.

Check it now: open your Jenkins URL — you must be redirected to Okta:

Log in, all done here.

Okta and our application for Jenkins SAML

Now let’s add a new application in Okta that will be able to pass a user’s group to Jenkins, for example — a DevOps group:

Okta configuration

Create a new application:

Set its name, icon:

Next, in the Single sign on URL и Audience URI (SP Entity ID) set ACS Endpoint — http://dev.ci.example.com/securityRealm/finishLogin:

To pass user groups from Okta to Jenkins, add a new field in the GROUP ATTRIBUTE STATEMENTS (OPTIONAL):

Name : Group

: Group Name format : Basic

: Basic Filter - Matches regex and value as .* to apply to all Okta's groups

On the next page, set I’m an Okta customer adding an internal app, and Finish.

Do not forget about Assignments.

Now, in the same way, as we did previously, click on the View Setup Instructions, copy IDP metadata and update Configure Global Security settings in Jenkins.

Copy a link to the Identity Provider metadata:

SAML configuration in Jenkins

Set this link to the IDP Metadata URL filed in Jenkins:

In Jenkins, change the Group Attribute’s value from the http://schemas.xmlsoap.org/claims/Group to just “Group”:

Actually, that’s all folks.

Jenkins Role-based Security

Going forward a bit (will add another post about Role-based plugin configuration) — an example of Role-based Security and groups in Jenkins.

A user in Okta and its groups:

Roles in Jenkins:

And a group DevOps with a test assigned:

Done.

Useful links