Implementing Devolved Constraints or Entitlements

This article goes into more depth about the implementation of Devolved Constraints or Entitlements.

Introduction

You may find the overview and mini-project to be a good place to start if you are not familiar with what devolved constraints and entitlements are. We are assuming that you have read that mini-project article.

This article is aimed at system managers who have a technical understanding of:

  • Authentication processes and concepts
  • Systems which support the SAML protocol
  • Talis Aspire Reading List Roles and Permissions

Devolved constraints is an optional piece of work that can be used to streamline how users (typically academics or other university staff) get granted permissions in Talis Aspire Reading Lists (TARL). We’ll deal with this subject first as it is the most common.

Devolved entitlements is an optional piece of work that can be used to streamline how TARL knows which modules a user (typically a student) is enrolled on in the university. This uses the same attribute as for devolved constraints, but with different data passed to Talis Aspire.

Which attribute should I release?

Talis’ Service Provider entity ID is shown below. Most IDentity Providers (IDPs) that support SAML2 can be configured to release specific attributes to specific Service Providers. 

https://login.talisaspire.com/entity

Talis uses SAML2. The attribute that you need to release is known by its friendly name as the eduPersonEntitlement and in SAML2 this looks like this:

urn:oid:1.3.6.1.4.1.5923.1.1.1.7

This attribute will be used for both Devolved Constraints and Entitlements.

Note in SAML1 this looked like urn:mace:dir:attribute-def:eduPersonEntitlement, but this is NOT the attribute that we will recognise.

In the rest of this document, we will use the friendly name to refer to the SAML2 attribute.

Important: If you are registered in the Tuakiri Federation (New Zealand), then you will need to let Talis know that you are implementing Devolved Constraints.

Devolved Constraints

What does a Devolved Constraint actually look like?

The constraint is simply a special URL which tells TARL which role and scope you wish to constrain. It takes the form:

http://{tenancyUrl}/constraints?role=ROLECODE&scope=MODULECODE

The scope parameter is optional – if you don’t supply it, TARL will assume you want to allow the user to perform the role at “tenancy level”.

Note at this time only the listpub role can be scoped, all other roles must be granted at tenancy level.

Important: {tenancyUrl} above is the HTTP tenancy url and NOT the HTTPS url. If you have a CNAME configured for Talis Aspire, the HTTP tenancy url will be the same as the CNAME.

Using the role membership information contained in your third party system, you build one or more of these special URLs into the eduPersonEntitlement attribute in the SAML 2 envelope that is sent back to Talis Aspire at login. As the set of devolved constraints is rebuilt each time the user logs in, the constraints Talis applies for the user will always mirror those of the single source of truth.

To make debugging easier, you can also place these special URLs into a web browser – Talis Aspire will return some XML to the browser describing the constraint you are requesting. Try this constraint from our test system, which describes a constraint for the list publisher role at tenancy level (i.e. the user can edit and publish any list):

http://lists.broadminsteruniversity.org/constraints?role=listpub

This returns the XML:

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:constraint="http://purl.org/vocab/resourcelist/constraint#">
  <rdf:Description rdf:about="http://lists.broadminsteruniversity.org/constraints/E9BE0636-E546-3047-EFFE-233358328D13">
    <rdf:type rdf:resource="http://purl.org/vocab/resourcelist/constraint#Constraint"/>
    <constraint:constrains rdf:resource="http://lists-sandbox.broadminsteruniversity.org/roles/list-publisher"/>
    <constraint:appliesTo rdf:resource="http://lists.broadminsteruniversity.org/"/>
  </rdf:Description>
</rdf:RDF>

The next example narrows the scope of the constraint to only allow the user to perform the list publisher role on lists attached to the module ABF203:

http://lists.broadminsteruniversity.org/constraints?role=listpub&scope=abf203

The XML for this one is a bit longer, so we won’t include it here (follow the link to see it). You will see that this time, four constraints are returned because ABF203 has four lists attached to it, Talis Aspire returns a constraint per list.

What about roles granted through the invites system in Talis?

Roles granted by the invites in TARL will remain active, and the two methods of granting roles may be used alongside each other.

What are valid role codes?

Role codes are configurable on a tenancy by tenancy basis, but in general these defaults are used.

Role Role Code
Node Editor nodeeditor
List Creator listcreator
List Publisher listpub
Library-Acquisitions libraryacquisitions
Role administrator roleadmin
Administrator admin

What are the minimum set of roles that you need to send?

If you want academics to be able to create and edit lists without sending them a manual invite, you will need to send the following roles in multiple eduPersonEntitlement attributes (the attribute can be repeated):

http://{tenancyUrl}/constraints?role=listpub
http://{tenancyUrl}/constraints?role=listcreator

Entitlements

Entitlements are setup the same way as Devolved Constraints - using the same SAML2 eduPersonEntitlement attribute. The only difference is that you would send through a space separated list of modules that the student was enrolled on.

ABC123 DEF456 GHJ345

Debugging and support

How can you validate that the correct role or entitlement is being sent?

If you have a test user, you can log into TARL and see what attributes have been captured.

Simply go to http://{tenancyUrl}/saml/attributes. If you are not logged in you will be prompted to log in. When you are logged into your IDP, you will see attributes that have been released to us by your IDP.

What support do we offer?

To avoid any doubt, Talis Education can not provide support and guidance for you local authentication and identity management strategy or implementation. This remains the responsibility of the institution, and we can only advise in respect to specific integration with Talis Products (e.g. what requirements the institution must meet when providing entitlements via SAML 2 from your IDP to our SP).

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk