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

Article ID:115000105752
Last Reviewed:2025-12-15()
4 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 log out. 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 log in 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>
▼

Encryption Configuration

If your OKTA administrators require Assertion Encryption, you must also configure the encryption settings in the SAML 2.0 Security Realm. If you do not explicitly configure encryption, the plugin will create a keypair that is valid for a year. It is, however, unknown to OKTA so it will fail to decrypt the encrypted assertions.

OKTA requires an encryption certificate in a PEM format. It is likely that you will get your private key and certificate from an internal Certificate Authority or generate them following the steps provided by the OKTA team. You should have two files in PEM format, which you would need to combine into a single Keystore file. The PKCS #12 standard is supported, so you can use openssl to create a Keystore, for example:

$ openssl pkcs12 -export -out saml-encryption.p12 -inkey saml-encryption.key -in saml-encryption.crt -name "OKTA"
▼

To configure the encryption:

  1. Ensure Keystore (e.g., saml-encryption.p12) is available on the server in the location readable by the operations center or controller

  2. In the Jenkins SAML 2.0 configuration, locate the Encryption Configuration checkbox and select it

  3. In the enabled section:

    1. Configure the Keystore path with the location chosen in Step 1

    2. Set Keystore password to the value provided to the openssl pkcs12 command

    3. Set Private Key Alias to the value of the -name openssl pkcs12 argument

    4. Private Key password is a required field. If the password wasn’t explicitly set on the key, you can enter the same value as in the Keystore password field

  4. Use "Test keystore" validation to ensure the configuration will work

The key and certificate used in the Jenkins Encryption Configuration must be identical to those uploaded to OKTA. Mismatched encryption credentials will cause authentication failures.
Ensure you have a plan to rotate the encryption certificate before expiry. Otherwise you will be locked out when authentication starts failing due to the expiry.

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

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.