How do I set up OKTA as Identity Provider in Jenkins?

Article ID:115000105752
Last Reviewed:2020-03-04()
3 minute readKnowledge base

Issue

  • How do I set up OKTA as an Identity Provider in Jenkins

Environment

Resolution

To set up OKTA as your IdP in Jenkins, you should perform configuration settings both in OKTA and in Jenkins.

OKTA Configuration Settings

The configuration settings to be performed in OKTA is well described in the OKTA documentation, please refer to the Create SAML app integrations. The documentation is clear and complete in general, but for Jenkins, we’ll need to pay attention to the following details:

  • The Single Sign On URL must be the http(s)://$Jenkins_URL/securityRealm/finishLogin as you can see in the following picture.

  • The NameID format can be set to EmailAddress, and the Application Username should be set to Okta User Name (These settings can also be seen in the image above).

  • If you want to be able to use your OKTA groups, you should provide a Group Attribute. You should name it Group, with the Basic Name Format, and include a Regex Filter .* as demonstrated by the picture below.

  • Once you have finished providing additional optional settings, you will complete the create operation and be able to get the Metadata needed to configure the IdP on the Jenkins side. By clicking on the link Identity Provider Metadata, as shown in the following picture.

Jenkins Configuration Settings

To use OKTA as an IdP for the SSO, you should have installed the SAML plugin. Once installed, you could then perform the following steps.

  • Go to Manage Jenkins  Security

  • Select "SAML 2.0" as "Security Realm"

  • Paste in the "IdP Metadata" section the metadata that you downloaded from the OKTA configuration step.

  • Leave the Display Name Attribute with the default value (you can tweak this value later).

  • Put Group in the group attribute section. You can also leave the default value as the plugin will not import the external groups to Jenkins.

  • It is also recommended that you set the value for the Username attribute to the same value that you have in the Display Name attribute.

  • If you set the Audience URI (SP Entity ID) in OKTA:

    • click on the Advanced Configuration checkbox

    • Enter the value of the OKTA "Audience URI (SP Entity ID)" in the "SP Entity ID" field

  • In the Authorization section, select the radio button Anyone can do Anything to avoid being locked outside Jenkins (this step is only intended to be performed in testing instances).

Please also note that Logout URL can be setup so you are redirected to the login URL when the session ends or you logout. This will result on a much more user-friendly experience, as it will avoid the error message indicating that the session has expired and you need to login again. This Logout URL can be obtained directly from the Identity Provider.

Once that you have all the configuration data set up and saved, you should click in the Service Provider Metadata link and check that you recover the expected information. You should receive information similar to the one shown below.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_071946c35ff24e5799d6672c0df4e1fe2529146" entityID="https://ci.example.com/cjoc/securityRealm/finishLogin" validUntil="2044-10-09T05:06:59.500Z">
  <md:Extensions xmlns:alg="urn:oasis:names:tc:SAML:metadata:algsupport">
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha384"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#hmac-sha256"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#hmac-sha384"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#hmac-sha512"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
    <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha384"/>
    <alg:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
  </md:Extensions>
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
    <md:Extensions xmlns:init="urn:oasis:names:tc:SAML:profiles:SSO:request-init">
      <init:RequestInitiator Binding="urn:oasis:names:tc:SAML:profiles:SSO:request-init" Location="https://ci.example.com/cjoc/securityRealm/finishLogin"/>
    </md:Extensions>
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ci.example.com/cjoc/securityRealm/finishLogin?logoutendpoint=true"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://ci.example.com/cjoc/securityRealm/finishLogin?logoutendpoint=true"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://ci.example.com/cjoc/securityRealm/finishLogin?logoutendpoint=true"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://ci.example.com/cjoc/securityRealm/finishLogin?logoutendpoint=true"/>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ci.example.com/cjoc/securityRealm/finishLogin" index="0"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
▼

Optional: Using an alternative application username

OKTA’s default login id enforces an email address format. This does not conform with Jenkins' typical user id format. To regain the traditional Jenkins username format, you may wish to use a custom field for the "Application username" during the OKTA configuration. In the example below, Jenkins will still use the unique id from OKTA; but, removes everything after the "@" symbol.

References