The hitchhiker’s guide to the TCS-personal galaxy
Don’t panic!
General stuff
The currently existing instances of the TCS-personal-portal and the TCS-eScience personal-portal are based on the Confusa software. So, instead of “the portal software”, the text will use the term “Confusa” from now on instead. In the design of the software, as always, some decisions had to be made, and from making decisions, very often peculiarities arise. So the intention of this guide is to explain some of the peculiarities of Confusa that became incorporated into the portals. So this is a good general reading to skim through before one progresses to connecting one’s institutions to the portal.
Don’t worry, Confusa is mostly harmless.
Confusa’s terminology (the lingo you just have to invent to sound cool)
Confusa comes with it’s own terms for a few things, due to the way it is designed. We tried to keep this reasonable, but to make references clearer, we did invent a few of our own words.
Subscribers
In short, we often call institutions subscribers. This is due to the fact that institutions have to usually undergo some procedures to use the portal, or in our words subscribe to it. First, their respective NREN has to be connected to the service. Then they have to make sure that the fulfill the stipulations of the CPS, most importantly, that they check the photo-IDs of user’s for who they set the certificate entitlement (if you can not fully follow this, don’t panic, more explanations come later). Then they have to clear the connection to the service with their NREN. Once this is done, the administrator of the NREN can set their status to “subscribed”. In total an institution, or a subscriber can be in one of three states:
- Unsubscribed The subscriber is connected to the portal, but has not yet signed the contractual agreements. Students or employees of the institution are thus not entitled to request certificates. This is the initial state of newly added subscribers.
- Subscribed The contract between the NREN and subscriber has been signed and the subscriber has agreed to follow the requirements placed upon it in the CP/CPS document. Users within the domain of the institution are entitled to request certificates, if their respective eduPersonEntitlement is set to the right value.
- Suspended Due to violations of the terms in the contracts, all activity for the subscriber has been ceased. No certificates are revoked, but subscriber users are not enabled to request new certificates. Once the issues have been resolved, the state can be changed back to ”Subscribed”.
Confusa’s access model
During the design of Confusa, we came up with a hierarchical access model, with three administrative roles and a user role. The roles that a logged on user in Confusa can have are
- NREN administrator or The administrator in a country to rule them all. Permissions include customization of the portal, definition of attribute mappings, the account with which the NREN connects to Comodo, definition of certificate properties, revocation and appointment of administrators.
- Subscriber administrator or (S)He, who rules over an institution. May perform institution wide revocation, appoint fellow and sub-administrators, define support information, revoke certificates within the student domain.
- Subscriber sub-administrator or Those who are not told the real name of their role. Sub-administrators may revoke certificates within the institution domain, but can not meddle with the subscriber settings. A handy role for support people who should be able to revoke certificates in case of an incident.
An administrator can have exactly one administrative role, so a NREN-administrator can not at the same time be a subscriber administrator.
For those who are into fancy graphics, the following one visualizes the hierarchical relation of different administrators. Note that subscriber admins may work with Confusa’s robotic revocation interface, which NREN-admins may not:
Confusa and identity federations (or where’s that DN come from?)
To use the portals, you need an identity federation. Or at least an identity provider that is able to export attributes about your users in either Shibboleth 1.3 or SAML2. 1 This is due to the fact that Confusa uses the attributes it receives from the identity provider to fill in the certificate’s subject-DN. And as you have probably figured, Confusa also needs a specific set of attributes to fill in the subject-DN. We have made those attributes mappable for both NRENs and subscribers, so NRENs and institutions can decide themselves with attributes they may want to use.
Required attributes and typically exported ones
The following table lists the attributes that Confusa requires to do its task and the attributes that are typically exported:
| User-info | Frequently exported attributes |
|---|---|
| Unique identifier | eduPersonPrincipalName, eduPersonTargetedID |
| Full name | cn, displayName |
| E-mail-address | |
| Organization name | eduPersonOrgDN, schacHomeOrganization, organizationName, scope (from eppn), entityID |
| Photo-ID checked | eduPersonEntitlement |
A verbose description of the attributes Confusa expects the IdP to export and how they are mapped can be found here.
| Note: We do recommend use of eduPersonPrincipalName for the unique-identifier, but if the federation setup demands it, using something else such as eduPersonTargetedID will be possible with Confusa 0.6. eduPersonEntitlement for confirming the performed check of the photo-ID is currently fixed and not mappable. |
Entitlement values and their semantics (…42)
The entitlement-attribute is used for two things in Confusa:
- Access control: By setting the entitlement to an admin value to provide a necessary but not sufficient condition for a user to become an admin. The other condition is that the admin’s principal identifier was added by another admin 2
- Requirement fulfillment: By setting the entitlement to an user value, the IdP confirms that the exported user information is the result of a photo-ID check.
The following entitlement-values are used, respectively, in the TCS-eScience portal and TCS-personal portal:
| Entitlement value | Entitlement semantics |
|---|---|
| urn:mace:terena.org:tcs:escience-user | User photo-ID checked and may request eScience certificates |
| urn:mace:terena.org:tcs:escience-admin | User is a subscriber admin for the eScience portal |
| urn:mace:terena.org:tcs:personal-user | User photo-ID checked and may request personal certificates |
| urn:mace:terena.org:tcs:personal-admin | User is a subscriber admin for the personal certificates portal |
1 Shibboleth 2.0 counts as SAML2.
2 Imagine this a bit like the English administrative system of the 17th to maybe the 20th century. In order for somebody to get a higher post, say the one of a judge, he needs the entitlement “Lord” set. However, being a “Lord” is not sufficient, the person still needs to be appointed by somebody else. Though, if the title “Lord” is not set for a person, any appointment will either be ineffective or not happen in the first place.