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.

What are my options?

• There are two routes to implementing Devolved Constraints.
  • Full Devolved Constraints — More work: You release the SAML attribute edu person entitlement urn:oid:1.3.6.1.4.1.5923.1.1.1.7 to us and tell us what role the user should have.
    • You are in complete control of which users you give the attribute to and what the role is.
    • You can change it at any time to suit you.
  • Scoped Affiliation Role Mapping — Less work: You probably already release the scoped affiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.9, so you need to tell us what scoped affiliation value should be mapped to which role.
    
    • You need to liaise with Talis Support to tell us which scoped affiliation should map to which role.
    • Roles granted in this way can ONLY be granted at the tenancy wide level.
    • This is the quickest option to set up and can be done after a short conversation with you.
• There is one route for implementing Devolved entitlements.
  • Student Module Entitlements — Most work: This route requires you to have data about which modules a student is enrolled on. That data needs to be available to your identity provider and released in the edu person entitlement urn:oid:1.3.6.1.4.1.5923.1.1.1.7 attribute. 

Scoped Affiliation Role Mapping

This method of doing Devolved Constraints means that we can map existing scoped affiliations to a role in Talis Aspire.

In order to set this up, you need to know 3 things.

1. You need to be releasing the scoped affiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.9 attribute. 
2. You need to know which values you are using for different groups of users. these will look like staff@my.uni.ac.uk
3. You will need to know which affiliation should map to which role in Talis Aspire.  For more about roles see What is a role and what is a permission.

You will then share that info with Talis Support and we will arrange the configuration of the mapping and let you know when it is ready to test.

Testing - it is suggested that you have access to one or more test user accounts who would have each of the scoped affiliations that you have mapped. Talis cannot test this for you.

If the scoped affiliation role has mapped correctly, the user's profile page will show the mapped roles on the 'roles' tab.  Roles granted in this way can ONLY be granted at the tenancy wide level.

Full Devolved Constraints and Student Module Entitlements

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.

• EU APAC - https://login.talisaspire.com/entity
• Canada North America - https://login.ca.talis.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 a short piece of text that tells TARL which role and scope you wish to constrain. It takes the form of a URL:

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

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 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 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.

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.  This would look like this:

ABC123 DEF456 GHJ345

"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 https://rl.talis.com/3/TENANCY/user_debug. 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.

Canadian institutions should use https://rl.ca.talis.com/3/TENANCY/user_debug

What support do we offer?

To avoid any doubt, Talis Education can not provide support and guidance for your 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).