Current Release: 1.0.0 (15/05/2015)
Audience: Enhancement Providers – ‘Providers’ and ‘Consumers’ of IdE Attributes
For access control purposes, or to allow higher level access, some research facilities such as virtual laboratories and cloud platforms require users to be identified as researchers. IdE enhances existing institution identities for users undertaking research activities in the Australian Higher Education sector by specifically identifying these users as a "researchers".
NeCTAR funded Virtual Laboratories (VL) and other AAF connected services will be able to use this information to make informed access control decisions specifically for researchers. IdE is designed for:
- Identity Providers (IdP) and Service Providers (SP) who wish to assert a Researcher attribute on users who are authenticated via AAF
- SP who wish to check if a user has an existing Researcher attribute
- AAF users who wish to apply for the researcher attribute via an IdP or SP as per list item 1.
The intended IdE Enhancement Provider is a research service provider that wishes to identify certain AAF users as researchers. As per the below Researcher:1 Definition, the definition of a researcher is different for different projects, organisations and service providers. Any organisation wishing to consume a researcher attribute should also be willing to assert it.
IdE was designed to support the varying use cases of NeCTAR funded virtual laboratories, and as such there are different ways to use IdE.
To be a provider and/or consumer of the researcher attribute, one or more of the following use cases will apply
- Need to assert and read a user’s researcher attribute to make AuthZ decisions
- Identify if a user already has a current (public) researcher assertion
- Allow users to apply for the researcher attribute from a provider.
Researchers are described and defined by a research project, as required by Enhancement Providers. Prior to submission to use IdE, providers should define what the attribute will allow access to, and why the attribute is required.
The definition of Researcher:1 may differ depending on the use case of the Service Provider (e.g. a Virtual Laboratory may have a different definition from a cloud supplier). An example being that certain research activities projects may require that only merit allocated users/researchers have access to resources/tools, where as some may only require that a user is associated with a research activity.
Providers who supply AAF with their definition and use of the attribute will add to the collaborative value of IdE. This will also allow consumers of the attribute to make AuthZ decisions, based on the definition given by various Providers.
To apply for IdE provider access, a request needs to be sent to AAF Support (email@example.com) containing the following information:
Name: The descriptive name of the provider (your organisation or research project)
Identifier: The identifier to use when specifying that this provider granted an attribute (e.g. AAF – shortened name)
Description: This required field is to give more detail about this provider, and what they do.
Upon successful application, AAF Support will do the initial set up of the provider and IdE will send a confirmation email inviting providers to AAF Identity Enhancement. IdE can then be accessed at https://ide.aaf.edu.au
AAF Support will assign new providers the privilege to assign enhancements (attributes) to AAF Authenticated Subjects (users).
All new providers will need to assign user/s to their administrator role. This administrator will then be able to assign roles to other users associated with the provider.
IdE users and administrators are simply AAF authenticated users who are assigned roles. After AAF support assigns the administrator role to a user, that user can then assign roles to other users associated with that provider.
For a provider to assign a role, an administrator will need to use IdE’s web interface (https://ide.aaf.edu.au/). The administrator can assign roles to a user by viewing the Members of a Role, and selecting the + Add Subject option.
Assign the appropriate role for the user:
API Read Only
Able to read query identity enhancements via the IdE API
Able to enhance identities and query identity enhancements via the IdE API
Web UI Read Only
Able to view identities enhanced by the provider
Web UI Read/Write
Can enhance an identity for a provider via the Web interface, but cannot assign, change or remove roles assigned to users
Has full administrative rights for the provider
API accounts are created by AAF and allow providers to programmatically interact with IdE. When an API account is requested, AAF will need to provide a certificate.
The provider will need to create a CSR for the server which will be calling the API. Upon receipt of the certificate AAF support will create an IdE API account with the following details:
Description: A descriptor for the API account, and how it will be used
X.509 CN: The CN field from the AAF-supplied certificate
Contact Name: The name of a person or team responsible for administering the API account
Contact Email Address: The contact email address of the person or team responsible for this API account
Documentation for developers wishing to use the IdE RESTful API is available. The server details will be provided by the AAF upon successful application to use IdE.
Documentation for developers wishing to use IdE support for the Shibboleth Simple Aggregation profile will be provided by the AAF upon application.
Example applications in Ruby have been made available for each of these approaches:
- Example application for integration via Rapid Connect + IdE RESTful API
- Example application for integration via a Shibboleth SP
Once set-up, providers have the option of using the web portal and/or RESTful interface to assert their support of a particular user’s status as a researcher, colloquially their ‘researcherness’.
An asserting group/organisation also has to delegate the ability to assert this support to multiple trusted administrators or RESTful clients of their choosing. The initial identification of researchers is via an email driven workflow.
Using Enhanced Identities
Services now have a common, centralised, AAF supported method of answering the question “is this user a researcher” when making local access control decisions in supporting authorisation policies put in place by business owners.
1. A SAML attribute authority endpoint which when queried for details of a particular user will return a SAML response containing the attribute eduPersonEntitlement and the researcher level or levels which have been asserted for the identified user (if any).
NB: SAML Simple Aggregation will only be able to provide the level of ‘researcherness’ achieved and not the party or parties who asserted it due to limitations in the SAML profile; and
2. A RESTful endpoint which when queried for details of a particular user will return a JSON response containing the researcher level or levels which have been asserted for the identified user (if any). In addition, for each level, the party or parties which asserted the value will be supplied. This will allow services to make access control decisions based on the provider who applied the enhancement.
Researchers will continue to utilise their institution credentials and commonly understood AAF login workflow as they understand it today, while being automatically granted access to a much wider range of resources across multiple services.
IdE was developed by Shaun Mangelsdorf and Bradley Beddoes for the Australian Access Federation and the National eResearch Collaboration Tools and Resources (NeCTAR) Project.