Note: replace https://keycloak.example.com with the root URL of your Keycloak service, replace jenkins.example.com with the name of your Jenkins host.
- Choose SAML 2.0 as a Security Realm
- Set the
IdP Metadata URL
tohttps://keycloak.example.com/realms/{realm}/protocol/saml/descriptor
, where{realm}
is the Realm of your client - Set the
Refresh Period
to1440
(24h, suggested value) - Click
Validate IdP Metadata
to make sure metadata can be fetched - Click
Apply
- Find
Service Provider Metadata
link and save it as an XML file, e.g.,jenkins-sp-metadata.xml
Using an entity descriptor to create a client is the reference documentation.
In a different tab in the Keycloak admin interface:
- On the
Clients
page of the same realm as above chose toImport client
- Select above
jenkins-sp-metadata.xml
as yourResource file
- (Optional) Give a meaningful Name and Description
- Save
- Find "Name ID format" field and change to
username
orpersistent
- Save your change
In the client details of the newly imported client:
- Switch to
Client scopes
- Open a
dedicated
client scope Add predefined mappers
- Choose
X500 email
,X500 givenName
,X500 surname
and clickAdd
- Open the newly added
X500 email
mapper and note theSAML Attribute Name
, e.g.,urn:oid:1.2.840.113549.1.9.1
- Repeat previous step for given name or surname depending on your preference of Display Name on the jenkins side, e.g.,
urn:oid:2.5.4.42
for given name. - For the sake of an example we will use a predefined
Role list
mapper as a source of groups (SAML Attribute Name
isRole
). However, depending on your use case one more mapper might be needed to share group membership with Jenkins.
Back on the Jenkins Security page:
- Set "Email Attribute" to the value noted in step 5 above
- Set "Display Name Attribute" to the value noted in step 6 above
- Set "Group Attribute" to the value noted in step 7 above
- "Save"
Test the authentication in an Incognito Window or a different browser.
For more details about the SAML Plugin configuration take a look at Configuration Guide For troubleshooting steps and know issue see Troubleshooting