Skip to main content
All CollectionsHelp CenterSSO Implementations
Configuring SSO with Shibboleth
Configuring SSO with Shibboleth
Franz Prowant avatar
Written by Franz Prowant
Updated over 2 weeks ago

⚠️ We currently don't support clicking on the app tile within Shibboleth, users must access the Cheqroom login page. We recommend that you bookmark that link for faster access. This is because we only support SP-initiated SSO flow.

Add Cheqroom in Shibboleth

  • Download Cheqroom metadata See Get Cheqroom metadata to add in Shibboleth

  • Upload it to Shibboleth in %{idp.home}/metadata/cheqroom-metadata.xml

  • Add MetadataProvider config for Cheqroom at the following location: %{idp.home}/conf/metadata-providers.xml.

<MetadataProvider id="CheqroomMD" 
xsi:type="FilesystemMetadataProvider" 
metadataFile="%{idp.home}/metadata/cheqroom-metadata.xml" maxRefreshDelay="PT48H"> 
</MetadataProvider>

  • Add RelyingParty config for Cheqroom at the following location: %{idp.home}/conf/relying-party.xml

<bean parent="RelyingPartyByName" c:relyingPartyIds="<entityID>"> <property name="profileConfigurations"> 
<list> 
<bean parent="SAML2.SSO" 
p:encryptAssertions="false" p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" /> 
<bean parent="SAML2.Logout" p:signRequests="true" /> 
</list> 
</property> 
</bean>

Don’t forget to replace c:relyingPartyIds attribute value <entityID> with the Audience URI (Entity ID) value (f.e urn:amazon:cognito:sp:us-west-2_o13Rvbcmc). Please see Get Cheqroom metadata to add in Shibboleth for more information.

  • Add SAML attributes at the following location: %{idp.home}/conf/attribute-resolver.xml If you already have these attributes configured, you can skip this step

<AttributeDefinition xsi:type="Simple" id="email"> 
<InputDataConnector ref="myLDAP" attributeNames="mail"/>      <AttributeEncoder xsi:type="SAML2String" 
name="email" 
friendlyName="Email Address" 
encodeType="false" /> 
</AttributeDefinition> 

<resolver:AttributeDefinition xsi:type="Simple" id="firstName">     <InputDataConnector ref="myLDAP" attributeNames="givenName"/> <AttributeEncoder xsi:type="SAML2String" 
name="firstName" 
friendlyName="First Name" 
encodeType="false" /> 
</AttributeDefinition> 

<AttributeDefinition xsi:type="Simple" id="lastName"> 
<InputDataConnector ref="myLDAP" attributeNames="sn"/> 
<AttributeEncoder xsi:type="SAML2String" 
name="lastName" 
friendlyName="Last Name" 
encodeType="false" /> 
</AttributeDefinition>

AttributeEncoder name attribute defines how the value will be names in the SAML response, this is also the name that you will need to you want to configure the attribute mapping in Cheqroom.

  • Add Attribute filter config to release the attributes to Cheqroom

<AttributeFilterPolicy id="releaseToCheqroom"> 
<PolicyRequirementRule xsi:type="Requester" value="<entityID>" /> <AttributeRule attributeID="email" permitAny="true" /> 
<AttributeRule attributeID="firstName" permitAny="true" /> 
<AttributeRule attributeID="lastName" permitAny="true" /> </AttributeFilterPolicy>

Don’t forget to replace PolicyRequirementRule attribute value <entityID> with the Audience URI (Entity ID) value (f.e urn:amazon:cognito:sp:us-west-2_o13Rvbcmc). Please see Get Cheqroom metadata to add in Shibboleth for more information.

  • Update saml-nameid.xml at the following location: %{idp.home}/conf/saml-nameid.xml

<bean parent="shibboleth.SAML2AttributeSourcedGenerator" p:format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" p:attributeSourceIds="#{ {'email'} }"> 
<property name="activationCondition"> 
<bean parent="shibboleth.Conditions.RelyingPartyId" c:candidates="<entityID>" /> 
</property> 
</bean>

Don’t forget to replace c:candidates attribute value <entityID> with the Audience URI (Entity ID) value (f.e urn:amazon:cognito:sp:us-west-2_o13Rvbcmc). Please see Get Cheqroom metadata to add in Shibboleth for more information.

Get Cheqroom metadata to add in Shibboleth

  • Log in to your Cheqroom account

  • Go to Settings > Authentication

  • Enable or edit SSO configuration:

    • If you haven’t enabled your SSO configuration already, click the Enable SAML SSO toggle

    • If SAML SSO is already enabled, click Edit SSO Configuration

  • The Cheqroom metadata section provides all required information

  • Click Download

Get Shibboleth metadata to enter in Cheqroom

The metadata can be provided either as a URL or as an XML file:

  • Metadata URL

    The URL format for IdP metadata generally looks like this:

    https://<your-idp-domain>/idp/shibboleth

    <your-idp-domain>: Replace this with your organization's specific domain for the IdP.
    ​

    Other common Shibboleth IdP urls are:

    • [https://md.incommon.org/entities/](<https://md.incommon.org/entities/>)<entity-id> if your organization is part of the InCommon Federation

    • https://<your-idp-domain>/idp/profile/Metadata/SAML
      ​

  • Metadata XML file

    If a metadata URL is not available, you can upload the IdP metadata file directly. This file is typically generated and available on your Shibboleth server at the following path:

    %{idp.home}/metadata/idp-metadata.xml

    If you encounter any issues obtaining the metadata file, contact your organization’s IT support team for assistance.
    ​

Enable SSO in Cheqroom

  • Log in to your Cheqroom account

  • Go to Settings > Authentication

  • Click Enable SAML SSO toggle

  • Choose Shibboleth as SAML Identity Provider

  • Cheqroom Metadata is needed to setup a Cheqroom application in Shibboleth, see Add Cheqroom in Shibboleth

  • Enter metadata url of Shibboleth, see Get Shibboleth metadata to enter in Cheqroom

  • Click Next to go to the Settings configuration step

  • Roles configuration

    • Choose a Default role, this will be assigned to a user who logs in through Shibboleth but has no assigned role. Here we recommend using a role that hasn't got a lot of permissions (for example the Equipment Viewer role)

    • Choose how user roles are managed, this lets you choose if you want to manage the roles from Shibboleth or keep the role management in Cheqroom. See Configure how roles are managed for SSO for more information.

  • User groups configuration This option is only available if you have created some user groups for your account, see Create User Groups

  • Click Next to go the the Attribute mappings step

  • Click Next to go the the Test connection step


Configuring User Roles in Shibboleth

To make the configuration of user roles more clear, we will be using an example use case with a LDAP schema tailored with students categorized by their grades, teachers associated with departments, and staff roles:

ObjectClass

Member Of

CN

sAMAccountName

User principal name

InetOrgPerson

grade_10_students

student_1

student1

student1@school.edu

InetOrgPerson

grade_11_students

student_2

student2

student2@school.edu

InetOrgPerson

grade_12_students

student_3

student3

student3@school.edu

InetOrgPerson

grade_12_students

student_4

student4

student4@school.edu

InetOrgPerson

grade_10_students

student_5

student5

student5@school.edu

InetOrgPerson

math_department

teacher_math_1

tmath1

tmath1@school.edu

InetOrgPerson

science_department

teacher_science_1

tscience1

tscience1@school.edu

InetOrgPerson

school_staff

librarian_1

librarian1

librarian1@school.edu

InetOrgPerson

school_staff

counselor_1

counselor1

counselor1@school.edu

  • Add MappedAttributeDefinition for cheqroom role at the following location %{idp.home}/conf/attribute-resolver.xml

    • InputDataConnector Here you indicate which LDAP field you will use to determine your the Cheqroom role, here we will use memberOf

    • AttributeEncoder name should be cheqroom__role

    • Add a ValueMap per role you want to configure

      • ReturnValue Here you need to paste the role value you want to return for the given memberOf values. See Configure how roles are managed for SSO to get role value

      • SourceValue Add a SourceValue for each memberOf value you want to assign the role

<AttributeDefinition xsi:type="Mapped" id="cheqroom__role"> <InputDataConnector ref="myLDAP" attributeNames="memberOf"/> <AttributeEncoder xsi:type="SAML2String" name="cheqroom__role"/> <ValueMap> <ReturnValue>super_admin</ReturnValue> <SourceValue>math_department</SourceValue> <SourceValue>science_department</SourceValue> <SourceValue>school_staff</SourceValue> </ValueMap> <ValueMap> <ReturnValue>self_service</ReturnValue> <SourceValue>grade_10_students</SourceValue> <SourceValue>grade_11_students</SourceValue> <SourceValue>grade_12_students</SourceValue> </ValueMap> </AttributeDefinition>

Example were math/science/staff members will be assigned super_admin role and students will be assigned self_service role

  • Add attribute rule for cheqroom__role at the following location: %{idp.home}/conf/attribute-filter.xml

<AttributeFilterPolicy id="releaseToCheqroom"> <PolicyRequirementRule xsi:type="Requester" value="<entityID>" /> <AttributeRule attributeID="email" permitAny="true" /> <AttributeRule attributeID="firstName" permitAny="true" /> <AttributeRule attributeID="lastName" permitAny="true" /> **<AttributeRule attributeID="cheqroom__role" permitAny="true" />** </AttributeFilterPolicy>

Add cheqroom__role AttributeRule


Configuring User Groups in Shibboleth

To make the configuration of user groups more clear, we will be using an example use case with a LDAP schema tailored with students categorized by their grades, teachers associated with departments, and staff roles:

ObjectClass

Member Of

CN

sAMAccountName

User principal name

InetOrgPerson

grade_10_students

student_1

student1

student1@school.edu

InetOrgPerson

grade_11_students

student_2

student2

student2@school.edu

InetOrgPerson

grade_12_students

student_3

student3

student3@school.edu

InetOrgPerson

grade_12_students

student_4

student4

student4@school.edu

InetOrgPerson

grade_10_students, grade_11_students, grade_12_students

student_5

student5

student5@school.edu

InetOrgPerson

math_department

teacher_math_1

tmath1

tmath1@school.edu

InetOrgPerson

science_department

teacher_science_1

tscience1

tscience1@school.edu

InetOrgPerson

school_staff

librarian_1

librarian1

librarian1@school.edu

InetOrgPerson

school_staff

counselor_1

counselor1

counselor1@school.edu

In Cheqroom itself we will assume we have user groups for 10th-grade students, 11th-grade students and 12th-grade students

  • Add ScriptedAttributeDefinition for cheqroom user group at the following location %{idp.home}/conf/attribute-resolver.xml

    • InputDataConnector Here you indicate which LDAP field you will use to determine your the Cheqroom user group, here we will use memberOf

    • AttributeEncoder name should be cheqroom__user_group

    • Add a Script you want to configure
      ​Here you need to paste the user group value you want to return for the given memberOf values. See Configure how User Groups are managed for SSO to get user group values

<AttributeDefinition id="cheqroom__user_group" xsi:type="ScriptedAttribute"> 
<InputDataConnector ref="myLDAP" attributeNames="memberOf"/> <AttributeEncoder xsi:type="SAML2String" name="cheqroom__user_group"/> <Script> 
<![CDATA[ 
cheqroom__user_group.getValues().clear(); // Check if memberOf has values before processing 
if (!memberOf.getValues().isEmpty()) { 
for (i = 0; i < memberOf.getValues().size(); i++) { 
value = memberOf.getValues().get(i); 
if (value.contains("grade_10_students")) { cheqroom__user_group.getValues().add("gybbPrjCNrbxV6sZ8XdSY"); 
} 
if (value.contains("grade_11_students")) { cheqroom__user_group.getValues().add("nxoWkUvxHkpeszoyxyj4py"); 
} 
if (value.contains("grade_12_students")) { cheqroom__user_group.getValues().add("4sx9cGaxG78w6Ge5YNhEk6"); 
} 
} 
} 
]]> 
</Script> 
</AttributeDefinition>

Example were we assign a different user group based on memberOf values that match specific grade values

  • Add attribute rule for cheqroom__user_group at the following location: %{idp.home}/conf/attribute-filter.xml

<AttributeFilterPolicy id="releaseToCheqroom"> 
<PolicyRequirementRule xsi:type="Requester" value="<entityID>" /> 
<AttributeRule attributeID="email" permitAny="true" /> 
<AttributeRule attributeID="firstName" permitAny="true" /> 
<AttributeRule attributeID="lastName" permitAny="true" />
<AttributeRule attributeID="cheqroom__user_group" permitAny="true" /> </AttributeFilterPolicy>

Add cheqroom__user_group AttributeRule


Troubleshooting common issues

Related Articles
Configuring Your SSO Attribute Mapping
Configuring SSO with OneLogin
Configuring SSO with Okta
Configuring SSO with ADFS
Configuring SSO with SAML IdP
Did this answer your question?