Skip to content
Scalekit Docs
Go to Dashboard

Shibboleth SAML

This guide walks you through configuring Shibboleth as your SAML identity provider for the application you are onboarding, enabling secure single sign-on for your users. You’ll learn how to set up a Shibboleth identity provider, configure SAML settings, map user attributes, and connect it to Scalekit. By following these steps, your users will be able to seamlessly authenticate using their Shibboleth credentials.

Configure Shibboleth Identity Provider

Section titled “Configure Shibboleth Identity Provider”

  1. Access Shibboleth configuration files

    Section titled “Access Shibboleth configuration files”

    Navigate to your Shibboleth IdP installation directory. The configuration files are typically located in the conf/ directory.

    Key configuration files you’ll need to modify:

    • conf/idp.properties
    • conf/relying-party.xml
    • conf/metadata-providers.xml
    • conf/saml-nameid.xml
    • conf/attributes/inetOrgPerson.xml

  2. Configure Entity ID

    Section titled “Configure Entity ID”

    Open the conf/idp.properties file and locate the entity ID configuration. The entity ID should be based on your Shibboleth IdP host.

    # Example entity ID configuration
    idp.entityId = https://your-shibboleth-url/idp/shibboleth

    Copy this entity ID value and paste it into the Entity ID field in your Scalekit SSO Configuration Portal.

  3. Configure SAML SSO URL

    Section titled “Configure SAML SSO URL”

    In your Shibboleth metadata file (metadata/idp-metadata.xml), locate the SingleSignOnService element with HTTP-Redirect binding:

    <SingleSignOnService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        Location="https://your-shibboleth-url/idp/profile/SAML2/Redirect/SSO"/>

    Copy the Location attribute value and paste it into the IdP Single Sign-on URL field in your Scalekit SSO Configuration Portal.

  4. Configure signing options

    Section titled “Configure signing options”

    In the conf/idp.properties file, ensure the following signing configuration:

    # When true, the decision to sign assertions is taken from WantAssertionsSigned property of SP metadata.
    # When false, the decision to sign assertions is taken from the p:signAssertions property of relying-party.xml
    # true is the default and recommended value.
    idp.saml.honorWantAssertionsSigned=true

    In the conf/relying-party.xml file, configure the relying party settings:

    <util:list id="shibboleth.RelyingPartyOverrides">
        <bean id="ScalekitSP" parent="RelyingPartyByName" c:relyingPartyIds="SCALEKIT_SP_ENTITY_ID">
            <property name="profileConfigurations">
                <list>
                    <bean parent="SAML2.SSO" p:signAssertions="false" p:encryptAssertions="true" p:signResponses="true"/>
                    <bean parent="SAML2.Logout" p:signResponses="true" />
                </list>
            </property>
        </bean>
    </util:list>

    Replace SCALEKIT_SP_ENTITY_ID with your Scalekit Entity ID from the SSO Configuration Portal. For example: https://your-app.scalekit.dev/sso/v1/saml/conn_123456789

  5. Configure security certificate

    Section titled “Configure security certificate”

    In your metadata/idp-metadata.xml file, locate the <KeyDescriptor use="signing"> elements. Copy the second certificate (front-channel configuration) and paste it into the Security Certificate field in your Scalekit SSO Configuration Portal.

    <KeyDescriptor use="signing">
        <!-- First certificate (back-channel) - do not use -->
    </KeyDescriptor>
    <KeyDescriptor use="signing">
        <!-- Second certificate (front-channel) - use this one -->
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>
                    <!-- Copy this certificate content -->
                </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </KeyDescriptor>

Configure Service Provider metadata

Section titled “Configure Service Provider metadata”

  1. Download SP metadata

    Section titled “Download SP metadata”

    In your Scalekit SSO Configuration Portal, save the SSO configuration and click Download Metadata to download the Service Provider metadata file. Refer to Generic SAML for detailed instructions.

  2. Configure metadata provider

    Section titled “Configure metadata provider”

    Move the downloaded metadata file to your Shibboleth IdP metadata directory:

    /opt/shibboleth-idp/metadata/scalekit-metadata.xml

  3. Update metadata-providers.xml

    Section titled “Update metadata-providers.xml”

    Open conf/metadata-providers.xml and add the following configuration:

    <MetadataProvider id="ScalekitMetadata"
                      xsi:type="FileBackedHTTPMetadataProvider"
                      minRefreshDelay="PT30S"
                      maxRefreshDelay="PT30S"
                      refreshDelayFactor="0.125"
                      disregardTLSCertificate="true"
                      backingFile="/opt/shibboleth-idp/metadata/scalekit-metadata.xml"
                      metadataURL="https://your-app.scalekit.dev/sso/v1/saml/conn_8xxx2"
                      backupFileInitNextRefreshDelay="PT30S">
        <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P30D"/>
        <MetadataFilter xsi:type="EntityRoleWhiteList">
            <RetainedRole>md:SPSSODescriptor</RetainedRole>
        </MetadataFilter>
    </MetadataProvider>

    Replace YOUR_SCALEKIT_ENTITY_ID with the Entity ID from your Scalekit SSO Configuration Portal.

Configure attribute mapping

Section titled “Configure attribute mapping”

  1. Configure SAML NameID

    Section titled “Configure SAML NameID”

    Open conf/saml-nameid.xml and ensure the following configuration is present in the <util:list id="shibboleth.SAML2NameIDGenerators"> section:

    <bean parent="shibboleth.SAML2AttributeSourcedGenerator"
          p:omitQualifiers="true"
          p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
          p:attributeSourceIds="#{ {'mail'} }" />

  2. Configure user attributes

    Section titled “Configure user attributes”

    Open conf/attributes/inetOrgPerson.xml and configure the attribute mappings. Ensure the following attributes are properly mapped:

    <bean parent="shibboleth.TranscodingRuleLoader">
        <constructor-arg>
            <list>
                <!-- Email attribute -->
                <bean parent="shibboleth.TranscodingProperties">
                    <property name="properties">
                        <props merge="true">
                            <prop key="id">mail</prop>
                            <prop key="transcoder">SAML2StringTranscoder SAML1StringTranscoder</prop>
                            <prop key="saml2.name">email</prop>
                            <prop key="saml1.name">urn:mace:dir:attribute-def:mail</prop>
                            <prop key="displayName.en">E-mail</prop>
                        </props>
                    </property>
                </bean>
    

                <!-- First name attribute -->
                <bean parent="shibboleth.TranscodingProperties">
                    <property name="properties">
                        <props merge="true">
                            <prop key="id">givenName</prop>
                            <prop key="transcoder">SAML2StringTranscoder SAML1StringTranscoder</prop>
                            <prop key="saml2.name">givenname</prop>
                            <prop key="saml1.name">urn:mace:dir:attribute-def:givenName</prop>
                            <prop key="displayName.en">Given name</prop>
                        </props>
                    </property>
                </bean>
    

                <!-- Last name attribute -->
                <bean parent="shibboleth.TranscodingProperties">
                    <property name="properties">
                        <props merge="true">
                            <prop key="id">sn</prop>
                            <prop key="transcoder">SAML2StringTranscoder SAML1StringTranscoder</prop>
                            <prop key="saml2.name">surname</prop>
                            <prop key="saml1.name">urn:mace:dir:attribute-def:sn</prop>
                            <prop key="displayName.en">Surname</prop>
                        </props>
                    </property>
                </bean>
            </list>
        </constructor-arg>
    </bean>

  3. Map attributes in Scalekit

    Section titled “Map attributes in Scalekit”

    In your Scalekit SSO Configuration Portal, ensure the attribute mapping section matches the attributes configured in your Shibboleth IdP:

    • Email: email
    • First Name: givenname
    • Last Name: surname

Configure Identity Provider in Scalekit

Section titled “Configure Identity Provider in Scalekit”

  1. Upload IdP metadata URL

    Section titled “Upload IdP metadata URL”

    In your Scalekit SSO Configuration Portal, under Identity Provider Configuration, select Configure using Metadata URL.

    Enter your Shibboleth IdP metadata URL:

    https://your-shibboleth-url/idp/shibboleth

  2. Test the connection

    Section titled “Test the connection”

    Click Test Connection to verify that your Shibboleth IdP is properly configured. If successful, you’ll see a success message.

    If the connection fails, review the error message and check your configuration settings.

  3. Enable the connection

    Section titled “Enable the connection”

    Once the test is successful, click Enable Connection to activate the SSO integration.

Advanced configurations Optional

Section titled “Advanced configurations ”

Encrypted assertions

Section titled “Encrypted assertions”

To enable encrypted assertions, update your conf/idp.properties:

# Set to true to make encryption optional
idp.encryption.optional = true

And in conf/relying-party.xml, ensure p:encryptAssertions="true" is set.

SAML signature method

Section titled “SAML signature method”

Shibboleth supports SHA256 and SHA1 algorithms for signing certificates. Configure your preferred algorithm in your certificate generation process.

IdP-initiated SSO

Section titled “IdP-initiated SSO”

To test IdP-initiated SSO, use the following URL format:

https://your-shibboleth-url/idp/profile/SAML2/Unsolicited/SSO?providerId=YOUR_SCALEKIT_ENTITY_ID&target=YOUR_RELAY_STATE_URL

Replace YOUR_SCALEKIT_ENTITY_ID with your Scalekit Entity ID and YOUR_RELAY_STATE_URL with your desired redirect URL.

Restart and test Optional

Section titled “Restart and test ”

  1. Restart Shibboleth IdP

    Section titled “Restart Shibboleth IdP”

    After making all configuration changes, restart your Shibboleth IdP service to apply the changes.

  2. Test authentication

    Section titled “Test authentication”

    Navigate to your application and attempt to sign in using SSO. You should be redirected to your Shibboleth IdP login page.

  3. Verify user attributes

    Section titled “Verify user attributes”

    After successful authentication, verify that user attributes are properly mapped and displayed in your application.

With this configuration, your Shibboleth IdP is now integrated with Scalekit, enabling secure single sign-on for your users. Users can authenticate using their Shibboleth credentials and access your application seamlessly.