This integration guide has been tested on Shibboleth version 4 and version 5.
Note
Throughout this guide, %{idp.home} is the directory where you installed your Shibboleth Identity Provider. When configuring Shibboleth, make sure to replace %{idp.home} with your specific path (e.g. /opt/shibboleth)
Preliminary steps
1. Ensure Compatibility with SAML2 Endpoints
To ensure that your Shibboleth IdP is compatible with SAML2 endpoints, you need to locate and inspect the IdP metadata file.
This file is typically stored at the location %{idp.home}/metadata/idp-metadata.xml.
Check the <SingleSignOnService> entries in the metadata file to verify whether the existing endpoints are compatible with SAML2.
Typically, the base URL is already configured in your IdP settings and corresponds to something like https://idp.example.org/idp/profile, where idp.example.org is the IdP’s domain in this example.
Note: The URLs above are provided as examples. Replacehttps://idp.example.org/idp with the actual domain and base path used by your IdP.
These bindings should already be present in your metadata file. If you do not see them, you will need to add these entries manually to ensure your IdP supports the required SAML2 endpoints. Do not replace any existing entries; simply append these lines to your metadata file as necessary.
2. Download IdP metadata file
Download and store the metadata XML file from your Shibboleth IDP, usually at the following location %{idp.home}/metadata/idp-metadata.xml .
Example of idp-metadata.xml with SAML2 endpoint compatibility
After selecting Shibboleth as SSO system, fill in a name to identify the integration.
Then upload the IdP metadata XML file (downloaded in the preliminary step).
Once the name is filled and the file is uploaded, click the Save button. This action will save the integration data in the Cusna system.
Download the Cusna metadata XML file from the download section that will appear. Rename the metadata file to cusna-metadata.xml .
There are multiple ways to configure the IdP to correctly communicate with the Cusna SP.
The following one is one general option:
1. Provide SP metadata with static file system metada provider
Upload the Metadata File
First, upload the cusna-metadata.xml file (which you downloaded in the previous step) to a folder on the Shibboleth server. For example, place it in the following directory:
%{idp.home}/metadata/
Edit the Metadata Provider Configuration
Next, open the Shibboleth metadata provider configuration file metadata-providers.xml. This file can be found at the following location:
%{idp.home}/conf/metadata-providers.xml
Add the Metadata Provider Entry
In metadata-providers.xml, add the following entry to include the Cusna metadata file as a static file system metadata provider:
To establish a trust relationship between Shibboleth and Cusna, you need to define a new RelyingParty element in the Shibboleth configuration file located at:
%{idp.home}/conf/relying-party.xml
Edit the Relying Party Configuration
Open the relying-party.xml file and add the following XML snippet to define the Cusna service provider (SP):
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<!--
Already existent relying parties
...
-->
<!-- Relying Party Configuration for Cusna -->
<bean parent="RelyingPartyByName" c:relyingPartyIds="https://cusnaio.cloud4wi.com/saml2/lynx/v1/289e7f7522caec89e43537c78b997bbb145f783b8bcb367fe74e681f71847b86">
<property name="profileConfigurations">
<list>
<!-- Shibboleth SSO Configuration -->
<bean parent="Shibboleth.SSO" p:postAuthenticationFlows="attribute-release" />
<!-- SAML2 SSO Configuration -->
<bean parent="SAML2.SSO"
p:encryptAssertions="false"
p:encryptNameIDs="false"
p:signResponses="false"
p:signAssertions="true"
p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" />
</list>
</property>
</bean>
<!-- You can add more Relying Party configurations below if needed -->
</beans>
3. SAML attribute mapping
To ensure proper communication between your Shibboleth Identity Provider (IdP) and the Cusna Service Provider (SP), you must map the attributes in a way that Cusna can understand. The attribute names must comply with the SAML2 standard and be correctly mapped to the expected values.
Please note that the attribute naming matches with the SAML2 standard.
Internal Attribute
SAML Attribute Name
Required
mail
urn:oid:0.9.2342.19200300.100.1.3
yes
givenName
urn:oid:2.5.4.42
no
sn
urn:oid:2.5.4.4
no
eduPersonAffiliation
urn:oid:1.3.6.1.4.1.5923.1.1.1.1
no
The following steps guide you through configuring your Shibboleth IdP to send the required attributes in a format that Cusna can process.
This procedure will ensure that the configuration for Cusna does not interfere with other Service Providers (SPs) that may also be configured on your IdP.
Define new Cusna specific Attribute Mappings inattribute-resolver.xml
To start, you need to define the necessary attribute mappings in the attribute-resolver.xml file, which is located in:
%{idp.home}/conf/attribute-resolver.xml
Add the following definitions to this file to map the required attributes:
Define Attribute Release Policy in attribute-filter.xml
Next, configure the attribute-filter.xml file to ensure that only the attributes necessary for Cusna are released. This file is located in:
%{idp.home}/conf/attribute-filter.xml
Add the following filter policy to the file:
<?xml version="1.0" encoding="UTF-8"?>
<AttributeFilterPolicyGroup xmlns="urn:mace:shibboleth:2.0:afp"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:mace:shibboleth:2.0:afp afp.xsd">
<!-- Release attributes for Cusna -->
<AttributeFilterPolicy id="ReleaseCusnaMappedAttributes">
<PolicyRequirementRule xsi:type="Requester" value="%{entityID}"/>
<!-- Email -->
<AttributeRule attributeID="cusnaEmail">
<PermitValueRule xsi:type="ANY"/>
</AttributeRule>
<!-- First Name -->
<AttributeRule attributeID="cusnaGivenName">
<PermitValueRule xsi:type="ANY"/>
</AttributeRule>
<!-- Last Name -->
<AttributeRule attributeID="cusnaSn">
<PermitValueRule xsi:type="ANY"/>
</AttributeRule>
<!-- Group IDs -->
<AttributeRule attributeID="cusnaGroups">
<PermitValueRule xsi:type="ANY"/>
</AttributeRule>
</AttributeFilterPolicy>
</AttributeFilterPolicyGroup>
PolicyRequirementRule: Ensures that these attributes are only released to the Cusna SP by checking the entityID of the requesting SP. The value="%{entityID}" should match the entityID in the Cusna metadata XML file.
AttributeRules: Each attribute (cusnaEmail, cusnaGivenName, cusnaSn, cusnaGroups) is released to the requesting SP with a PermitValueRule that allows all values for each attribute.
Make sure the Requester matches the entityID value specified in Cusna metadata XML file cusna-metadata.xml.
This configuration ensures that only Cusna SP receives the required attributes with the specified names, without affecting other SPs configured on your IdP.
At this point the integration is correctly configured and users can login using their own credentials.
