How do I setup OKTA as Identity Provider in Jenkins?

Issue

How do I setup OKTA as Identity Provider in Jenkins

Environment

SAML Plugin
CloudBees Jenkins Enterprise

Resolution

To setup 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, that you can find in the following link. 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 including a Reg. Ex. Filter .* as you can see in the picture below.

Once that you have finished providing additional optional settings you will complete the create operation and will 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

In order to user OKTA as IdP for the SSO, you should have installed the SAML plugin. Once installed, you could then perform the following steps.

Go to "Configure Global Security"
Check "Enable security"
Select "SAML 2.0"
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 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, 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.

<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
                 Destination="https://localhost:8888/simplesamlphp/www/module.php/saml/sp/saml2-acs.php/example-okta-com"
                 ID="id304067580046365441472203853"
                 InResponseTo="_2b16caecb21804d0271c7b45734978a31b122c0b9a"
                 IssueInstant="2017-02-02T03:13:05.114Z"
                 Version="2.0"
                 xmlns:xs="https://www.w3.org/2001/XMLSchema"
                 >
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                  Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
                  >https://www.orgname.okta.com</saml2:Issuer>
    <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#" />
            <ds:SignatureMethod Algorithm="https://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
            <ds:Reference URI="#id304067580045365441472303853">
                <ds:Transforms>
                    <ds:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                    <ds:Transform Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#">
                        <ec:InclusiveNamespaces xmlns:ec="https://www.w3.org/2001/10/xml-exc-c14n#"
                                                PrefixList="xs"
                                                />
                    </ds:Transform>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="https://www.w3.org/2001/04/xmlenc#sha256" />
                <ds:DigestValue>hF6r9lkeTRvgbJA/0bc8ykvCqES8rUzuW9YYShmlQvo=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>I82goYxTr5q2D+eWvj6O+DnqOG/xtAStirrgTY1dpBQ2plrI6e4t1g6stXZ47+y3qX81xSPv2pcVXp6NlhxU2twBK+1xL2tduymVrwWWI4VATdx5SjmcYaH5FKaDn1ee6Vs7YtYDZJzJDqGe/+5SaemnstrVmXbjmKwDinO5ttvNsW8R1LBF+Zxr8ti+2Jkggn9PRoYp+J/MZ5+sMZgky2HB70u0vrwiL+4ELD/avj8FeeHBMJwqllWQ1qCZ5ELtRLXANCNge3Ur392HkGy4HB2t1EVcMAO8wZpAzHMnp6IozQM8+/2aPdDTapnv4kOj8scxsoZlbMHAZCgfl3lj7w==</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>MIIDpDCCAoygAwIBAgIGAVVfq86GMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEG
A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
MBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldnN1cHBvcnQxHDAaBgkqhkiG9w0BCQEW
DWluZm9Ab2t0YS5jb20wHhcNMTYwNjE3MTg0MTIyWhcNMjYwNjE3MTg0MjIyWjCBkjELMAkGA1UE
BhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV
BAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXZzdXBwb3J0MRwwGgYJ
KoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
qp10VJvKjqIEk30bv0WPw6XhZtTm19XfLrwyHRG1aYQshkcIolS9Vvp5SdL6dDEctdf5dznrQTlr
8Q+LUIC6JGnVzA/qgC1UpsXYdfaod0c35GM8HDsHni0MNUnHt/2MqDW6PkYoIdjniDp21wOCiORE
FGuC1kUQQJY2yQ8bQJVEKCEyIUPGXLMcQlbB0vAkbGeqz4HCZBX/n7wr/50MMQz8YOLSkx/0Ojls
sGEA6KAbdFutrvSUKIUeZc4XFfySm9KJ1Vi83PpacOfWuKyktjPR0mC6wK87PuN32boa4nQ2+BMf
v/qgx4e5RDnTYk2+iPcwN6nKxJfS66kKhpfMdwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQA8R607
iL9Sx9QKo31zG2xG24drYxaWta6G5XKcROkFk2ZVfRAhS9rx1WFXuCV5e/ys0z7jILWKisTkjegY
uubqy6awBbjDRxnUct0OdZU4siHWYjvL+SYOT2Pk8IwlD4HGNsee6WmURvfpL2Yib9Xc85qVp1W9
t7GU2GZVnOyU7a/JfAgDw79z5dH1BQsCW+nvgeO5VgFXVOSf7dBOB2PlwG5DlH5MgNa67eH3Wr9B
RKvwyyTfqfq9pgSmB9xNVJIeVZbbZGTlNGqJti24E0AiIPggtxg5NJ+HHnEQ5RxdSsR4fbMz9i0K
/bXt6hPgGu7xYRSv1RfvKcR1NjYk3nnD</ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
    <saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </saml2p:Status>
    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                     ID="id304067580046759701759203951"
                     IssueInstant="2017-02-02T03:13:05.114Z"
                     Version="2.0"
                     xmlns:xs="https://www.w3.org/2001/XMLSchema"
                     >
        <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
                      xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                      >https://www.orgname.okta.com</saml2:Issuer>
        <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="https://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
                <ds:Reference URI="#id304067580046759701759203951">
                    <ds:Transforms>
                        <ds:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#">
                            <ec:InclusiveNamespaces xmlns:ec="https://www.w3.org/2001/10/xml-exc-c14n#"
                                                    PrefixList="xs"
                                                    />
                        </ds:Transform>
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="https://www.w3.org/2001/04/xmlenc#sha256" />
                    <ds:DigestValue>S8mNiYKRl/EwtRMUnwqL8oLfaBNHpgf1Kl1fVmHboX4=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>ipdSi9HVuHisncXx5xOxTTdyV0i1yMRecpTWVq5HF8Tunc6GImyAd7c7bLGIxRVrqWaL49+eKzs/G906ekWd3/2O7MMXvXb3p9SnQF74mV90p+l+Pb3CnuPuithbF2dBgzUe+AadZs8ZrgfTnC+s7zx/ZKsjfK4JbUNC7zajXl0+PcoJUic3NVe5Gkda/+caKAVkIc7JvT6pkp3gEQhMowfb5YtsgO41HNYu92RmJCikPEGawgsc4PKzvrMUSZZa52XYrTTRgpt6RvYA2PRBuocExRS3M1oLpEgKrmJ9oCzESaMHuqulQbY8lRfZnehjl+tzg92W8YNkrR4qPaLlYA==</ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>MIIDpDCCAoygAwIBAgIGAVVfq86GMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEG
A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
MBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldnN1cHBvcnQxHDAaBgkqhkiG9w0BCQEW
DWluZm9Ab2t0YS5jb20wHhcNMTYwNjE3MTg0MTIyWhcNMjYwNjE3MTg0MjIyWjCBkjELMAkGA1UE
BhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV
BAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXZzdXBwb3J0MRwwGgYJ
KoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
qp10VJvKjqIEk30bv0WPw6XhZtTm19XfLrwyHRG1aYQshkcIolS9Vvp5SdL6dDEctdf5dznrQTlr
8Q+LUIC6JGnVzA/qgC1UpsXYdfaod0c35GM8HDsHni0MNUnHt/2MqDW6PkYoIdjniDp21wOCiORE
FGuC1kUQQJY2yQ8bQJVEKCEyIUPGXLMcQlbB0vAkbGeqz4HCZBX/n7wr/50MMQz8YOLSkx/0Ojls
sGEA6KAbdFutrvSUKIUeZc4XFfySm9KJ1Vi83PpacOfWuKyktjPR0mC6wK87PuN32boa4nQ2+BMf
v/qgx4e5RDnTYk2+iPcwN6nKxJfS66kKhpfMdwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQA8R607
iL9Sx9QKo31zG2xG24drYxaWta6G5XKcROkFk2ZVfRAhS9rx1WFXuCV5e/ys0z7jILWKisTkjegY
uubqy6awBbjDRxnUct0OdZU4siHWYjvL+SYOT2Pk8IwlD4HGNsee6WmURvfpL2Yib9Xc85qVp1W9
t7GU2GZVnOyU7a/JfAgDw79z5dH1BQsCW+nvgeO5VgFXVOSf7dBOB2PlwG5DlH5MgNa67eH3Wr9B
RKvwyyTfqfq9pgSmB9xNVJIeVZbbZGTlNGqJti24E0AiIPggtxg5NJ+HHnEQ5RxdSsR4fbMz9i0K
/bXt6hPgGu7xYRSv1RfvKcR1NjYk3nnD</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">userName</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="_2b16caecb21804d0271c7b45734978a31b122c0b9a"
                                               NotOnOrAfter="2017-02-02T03:18:05.114Z"
                                               Recipient="https://localhost:8888/simplesamlphp/www/module.php/saml/sp/saml2-acs.php/example-okta-com"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2017-02-02T03:08:05.114Z"
                          NotOnOrAfter="2017-02-02T03:18:05.114Z"
                          xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                          >
            <saml2:AudienceRestriction>
                <saml2:Audience>https://localhost:8888/simplesamlphp/www/module.php/saml/sp/metadata.php/example-okta-com</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement AuthnInstant="2017-02-02T03:13:05.114Z"
                              SessionIndex="_2b16caecb21804d0271c7b45734978a31b122c0b9a"
                              xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                              >
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
        <saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:Attribute Name="FirstName"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
                             >
                <saml2:AttributeValue xmlns:xs="https://www.w3.org/2001/XMLSchema"
                                      xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >FirstName</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="LastName"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
                             >
                <saml2:AttributeValue xmlns:xs="https://www.w3.org/2001/XMLSchema"
                                      xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >LastName</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="Email"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
                             >
                <saml2:AttributeValue xmlns:xs="https://www.w3.org/2001/XMLSchema"
                                      xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >firstname.lastname@example.com</saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>

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.