SAML – Secure Assertion Markup Language is used for federated authentication when some service which we need to get access to (a Service Provider), asks another service (an Identity Provider) to perform a user’s authentification.
Check the documentation
- Service Provider (SP): is a system where need to authenticate, in our case this will be Jenkins
- Identity Provider (IDP): is a system where users are stored and which 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:
- 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
In 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 need 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 which will have Access Roles assigned to users groups with rules limiting their access to various jobs (developers, backend, data analytics, etc)
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 reviewed in the Okta native 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 reviewed in the Okta и своё приложения для Jenkins SAML part of this post
Okta Community Created Jenkins SAML application
Go to the Okta > Add app, find a Jenkins SAML plugin:
Set the 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:
SAML configuration in Jenkins
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:
Okta and our application for Jenkins SAML
Now let’s add a new application in Okta which will be able to pass a user’s group from Okta to Jenkins, for example – a DevOps group:
Create a new application:
Set its name, logo:
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 format: 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”:
Jenkins Role-based Security
Going forward a bit (will add another post about Role-based plugin configuration) – a “preview” of the Role-based Security plugin and groups in Jenkins.
A user in Okta and its groups:
Roles in Jenkins:
And a group DevOps with a test assigned:
Also published on