Configuring SAML

As-of-version 1.0.4, the SAML plugin is verified by the CloudBees Assurance Program. If you use CloudBees CI version 2.73.2.1 or newer, it is recommended that you use the SAML plugin version verified with your release.

The SAML plugin only supports Authentication challenges, it does not synchronize "External" groups or roles in CloudBees CI. If your SAML Identity Provider (IdP) supports the Group attribute, you can configure it in the SAML Security Realm, and these groups will be retained and can be used in the configuration of Authorization Strategies.

SAML plugin configuration

The SAML plugin must be configured before moving forward. Follow the steps provided in the CONFIGURE.md file. At a minimum the IdP Metadata, Group Attribute, and Username Attribute fields should be configured.

After the SAML plugin has been configured, configure the Role-Based Access Control groups, and add RBAC group members using the groups being returned by your IdP. This allows the users be granted the correct authorization once they sign in via SAML.

IdP metadata configuration examples

IdP metadata must look like the example below. Usually, an IdP server can generate it for you, or you can request it from your provider. In cases where it is not available, it can be generated manually with the metadata from the server.

In the following example, EntityDescriptor contains data about the identity provider. The entityID attribute is its unique identifier. The rest of the IdP metadata contains information about how to sign and encrypt messages and the URLs to sign in and log out. For more information and additional references, see SAML 2.0 Metadata:

SAML Plugin 1.0.4 and earlier only supports urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect SingleSignOnService Binding.
SAML Plugin 1.0.5 adds support for the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST Binding.

IdP metadata has to be configured in Manage Jenkins Security Security Realm SAML SAML Identity Provider Settings IdP Metadata.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="https://SAML_SERVER/idp/">
    <!-- The SSO service at the identity provider -->
    <IDPSSODescriptor WantAuthnRequestsSigned="false"
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>...
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
    <!-- Supported Name Identifier Formats -->
    <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
    <!-- AuthenticationRequest Consumer endpoint -->
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://SAML_SERVER/idp"/>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://SAML_SERVER/idp"/>
</IDPSSODescriptor>
</EntityDescriptor>▼

When the AuthRequest is validated, the identity provider sends a SAMLResponse to [CI_URL]/securityRealm/finishLogin. This response contains information about the user, session ID, authorization groups, signature of message, and the session expiration. An XML message similar to the following one is expected:

<Response
    xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
    Destination="https://CI_URL/securityRealm/finishLogin"
    ID="..."
    InResponseTo="..."
    IssueInstant="..."
    Version="2.0">
    <ns1:Issuer xmlns:ns1="urn:oasis:names:tc:SAML:2.0:assertion"
        Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://SAML_SERVER/idp/</ns1:Issuer>
    <Status>
        <StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </Status>
    <ns2:Assertion xmlns:ns2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_4d406d6505202232c48a50726c55d58f548c"
        IssueInstant="..." Version="2.0">
        <ns2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://SAML_SERVER/idp/</ns2: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="#_4d406d6505202232c48a50726c55d58f548c">
                    <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#"/>
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="https://www.w3.org/2001/04/xmlenc#sha256"/>
                    <ds:DigestValue>...</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>...
            </ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>...
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <!-- User information -->
        <ns2:Subject>
            <ns2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">USER_NAME</ns2:NameID>
            <ns2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <ns2:SubjectConfirmationData InResponseTo="..." NotOnOrAfter="2016-04-18T19:06:23Z"
                Recipient="https://CI_URL/securityRealm/finishLogin"/>
            </ns2:SubjectConfirmation>
        </ns2:Subject>
        <!-- expiration of session -->
        <ns2:Conditions NotBefore="..." NotOnOrAfter="...">
            <ns2:AudienceRestriction>
                <ns2:Audience>https://CI_URL/securityRealm/finishLogin</ns2:Audience>
            </ns2:AudienceRestriction>
        </ns2:Conditions>
        <ns2:AuthnStatement AuthnInstant="..." SessionIndex="..."
            SessionNotOnOrAfter="...">
            <ns2:AuthnContext>
                <ns2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ns2:AuthnContextClassRef>
                </ns2:AuthnContext>
        </ns2:AuthnStatement>
        <!-- Authorization Groups -->
        <ns2:AttributeStatement>
            <ns2:Attribute name="groups">
                <ns2:AttributeValue>groupOne</ns2:AttributeValue>
                <ns2:AttributeValue>groupTwo</ns2:AttributeValue>
                <ns2:AttributeValue>groupThree</ns2:AttributeValue>
            </ns2:Attribute>
        </ns2:AttributeStatement>
    </ns2:Assertion>
</Response>▼

Federation Service Provider configuration example

There are some special configurations where even after validating the IdP metadata and performing other tests, the authentication does not work. If you are using a Federation Service Provider (FSP) such as SiteMinder, and your profile configuration requires that the SAML request includes certificate information, you will most likely get error 500. But on the CloudBees CI side, you will not see an exception as the FSP is just returning a 500-Server Error. You will see some errors in the FSP like the following ones:

Example output for a Federation Service Provider

[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][resource is: /]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][resolved variable list is: ]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Calling authorizeEx to invoke SAML2 assertion generator.]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Request to policy server for generating saml2 assertion/artifact based on selected profile. [CHECKPOINT = SSOSAML2_GENERATEASSERTIONORARTIFACT_REQ]]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Transient IP check: false]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Result of authorizeEx call is: 1.]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Received the assertion/artifact response based on profile selected. [CHECKPOINT = SSOSAML2_RECEIVEDASSERTION_RSP]]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Not enforcing ForceAuthnTimeouts.]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Received the following response from SAML2 assertion generator: SAML2Response=NO.]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Transaction with ID: ID failed. Reason: FAILED_INVALID_RESPONSE_RETURNED]
[DATE][TIME][1044][4500]Transaction_ID][SSO.java][processAssertionGeneration][Denying request due to "NO" returned from SAML2 assertion generator.]
[DATE][TIME][1044][4500]Transaction_ID][ErrorRedirectionHandler.java][redirectToErrorPage][Sending HTTP Error 500 ]▼

You must enable the Encryption Configuration check and provide the Keystore path and password so the plugin can use the required certificates. You must also enable the Auth Request Signature so that the key-pair can be used to authenticate and encrypt messages between the Service Providers and Identity Providers as allowed by the SAML standard.

For more information, refer to the following: