The NREN-admin's guide to the TCS-personal galaxy
...we have normality, I repeat we have normality. Anything you still can't cope with is therefore your own problem.
This guide has a Fika guarantee. It was written with the intention of capitalizing as little on your time as possible and thus giving you time for Fika. If you should miss any Fika due to configuring the portal for your NREN, please complain at tcs-portal and tell us what, in your opinion, needs improvement in the guide.
This guide is intended as a step to step guide about connecting your NREN to the TCS-escience-portal or TCS-personal-portal. If you need more general information about the portal's pecularities and setup, please consult the more general The hitchhiker's guide to the TCS-personal galaxy.
So let's go step by step through what you need to do to connect your NREN to either of the portals.
0. Make sure about which portal you want (for the buzzword-literate: "assess your requirements")
Do you need the eScience (Grid) certificates or personal certificates (e.g. for signing e-mails)? Generally you want both, so your customers can decide which type of certificate to request. In general you want both, as your customers can decide per individual person which certificate he can reqiuest. If you have no relations to the eScience Grid community ask for only normal Personal. The other option can always be added later can always add the other option later. The annual TERENA fee buys both types.
1. Import the portals' metadata into your federation's metadata aggregate
Or dependent on which model your federation follows, into your national IdP's metadata. The following metadata needs to be imported:
2. Provide your own federation metadata or metadata set to portal operations
Provide an URL to your federation metadata to portal operations. If you are not in touch already with operations, the easiest way to reach them is by mailing to tcs-portal-core.
3. Export the right set of attributes from the IdP that the NREN administrator will use
If your national federation deployment does not follow a hub and spoke model, probably more than one productive IdPs will be available within your federation. The attribute release does not have to be configured correctly for all of them directly in the beginning (even though it helps if as many as possible are available). But for setting up the rest it is important that you configure the IdP that you as the NREN admin will use to access the portal to release the correct set of attributes.
In Confusa 0.5 these attributes must be the following:
- eduPersonPrincipalName. This eduPersonPrincipalName needs to contain a globally unique persistent tag. Typically examples are 'firstname.lastname@example.org' or 'email@example.com'. This is not a mail address. The '@university.country' takes care of global uniqueness; the text in the first part might be a username or an administration number. Persistence means that once a particular principalName has ever been used for a person, it must not ever be used for another person. If you can not fulfill that requirement in your federation (for instance due to the way you construct your NetID), you may tell portal-operations to bootstrap your federation with another attribute for the unique identifier, such as eduPersonTargetedID. You must communicate that in the beginning, at least before any certificates have been issued to members of your constituency, because otherwise the namespace will be in flux, which is unacceptable.
- eduPersonEntitlement, containing urn:mace:terena.org:tcs:escience-user and/or urn:mace:terena.org:tcs:personal-user. Note: this value must only be set for users that are guaranteed to have a passport-verified identity! People need not be re-authenticated using passport if that was done earlier. Test identities are strictly forbidden, as are pseudonyms.
- Additionally, for the NREN and Subscriber admins, the values urn:mace:terena.org:tcs:escience-admin/urn:mace:terena.org:tcs:personal-admin are required.
- schacHomeOrganization OR eduPersonOrgDN identifying the institution/subscriber of the person within the NREN. E.g. for schacHomeOrganization "uvt.nl", or for eduPersonOrgDN "o=Hogwarts, dc=hsww, dc=wiz". It is also possible to use the scope from the ePPN as an organizational identifier, if you do not have multi-domain institutions or the IdP's entityID if there is a one to one relationship between subscribers and IdPs
- some representation of the full name (e.g.: 'cn', but can be differently named attribute). This full name will be the Common Name of the issued certificate. Examples of a Common Name: "S. Kramer" or "Thijs Nijssen".
- the user's email address (e.g.: attribute 'mail', but can be a differently named attribute). Email addresses end up in the certificate. On a per NREN base, the portal can be configured to support more than one mail address.
Note Using other unique identifiers than eduPersonPrincipalName will be possible with the next Confusa release 0.6 (which is due end of April 2010).
For a more verbose description of the attributes and the attribute mapping process, refer to the TCS-wiki article about operational requirements.
4. Provide your unique identifier as exported by your IdP
Example: If you use ePPN as your unique identifier and your IdP exports your ePPN as 'firstname.lastname@example.org', then portal operations needs 'email@example.com to bootstrap you as a new NREN admin.
By knowing your unique identifier portal operations can bootstrap you as the administrator for your NREN. Further NREN administrators and subscriber administrators can be added by yourself once you have logged in.
5. Define the attribute mapping for your NREN
Log in to the portal. If steps 0-4 were performed correctly, you will see in the menu that you are a NREN-admin, by being offered a View menu option which which you can switch between the User and NREN-Admin views:
In the NREN-Admin view, go to Attributes and define which attributes map to which informations that Confusa needs:
If a subscriber of yours needs to export different attributes, then that mapping can be overriden on the subscriber level. However, it is preferred if the subscriber does not need to do so. So pick something which works for your NREN and probably most subscribers and their respective IdPs.
6. Define the account with which the Comodo-CA is accessed
You should have received the account credentials when signing the contract for the TCS service with TERENA. Time to put them to use by telling them to the portal!
Note: It is strongly recommended to use a different sub-account for the eScience-portal than for the personal-portal. If the same account is used it will be impossible for the portal to distinguish which certificates were issued with the eScience-CA and which were issued with the personal-CA and users could see their personal certificates in the eScience portal and vice versa! Sub-accounts can be defined on the Comodo administrative interface.
Navigate your browser to the menu-point "NREN" -> "CA-account" in the NREN-admin view and enter the account credentials:
7. Define the portal settings for your NREN
Point your browser to "Settings" in the NREN-Admin view. Define contact information, language settings and the certificate validity period (personal certificates only). If you add a URL here, Confusa 0.6 and later will be able to guess the NREN-branding and forward the user to your NREN's own WAYF page, if such exists, upon logging in:
8. Add institutions (subscribers) to the portal
If you have cleared the internal procedures for a subscriber that are necessary so people within the subscriber's constituency can use the portal, time to add it to the portal so the subscriber can actually use it. Adding a subscriber is a bit involved so we will discuss this more step-by-step than the points above.
First, go to the "Subscribers" point in the NREN-admin menu, and then select "Add new":
A scary, lengthy, verbose form will appear. Don't panic, most of it is rather self-explaining. However, the first two steps are rather involved. In the section "Attribute name", enter the subscriber name as it is exported by the subscriber's IdP.
Next, you want to determine the organization name as it will go into the DN. That is really the string that will follow after the /O=... part of the certificate's subjectDN. Enter a more or less arbitrary value here, but think wisely before choosing it. Any change of the name will result in revocation of all certificates that were issued with that org-name. So you should choose a name for the subscriber that can stay stable over a longer period of time. In the eScience portal, that name will also be subject to Grid restrictions. I.e. it will only be allowed to contain ASCII characters and its length will be limited to 62 characters:
If your subscriber needs to use another attribute for the unique identifier as you have configured on the NREN-level, the form gives you the possibility to specify the name of that attribute. Untick the checkbox which says "Inherit from NREN-mapping" and enter the name of the attribute you want to configure for that particular subscriber. If the subscriber uses the same attribute for the UID as you have configured on the NREN-level, just leave the "Inherit from NREN-mapping" checkbox checked:
The next few form fields are standard information about the subscriber, such as helpdesk information, contact information and so on. Fill in appropriate values into these fields. What's important is the subscriber state. Only if the subscriber state is "Subscribed", users of the subscriber can request certificates. So if (and only if) you have already cleared all contractual details with the subscriber you are adding, set the subscriber state to "Subscribed":
9. Check the information that the portal has about you
Now you can verify if the attribute mapping and the subscriber-adding was actually successful. Click on the portal title in the header bar of the portal and check the information that is displayed in the "Info about you" box. Especially have a look at the Full-DN and control if it includes sane values:
10. Add administrators for the configured subscribers
If you point your browser to "Portals" -> "Admins" you see two control fields. With the upper, you can add fellow NREN-administrators, while with the lower you can add admins for the subscribers within your constituency. The latter is more important initially, so your subscribers can start to take care of their own configuration.
For every configured subscriber in the "Change subscriber" list, enter one or several unique identifiers of the admins. If the configured unique identifier is eduPersonPrincipalName, add one or several ePPNs here.
Note: If a subscriber admin with that identifier logs on, he or she does not automatically have admin-status. Additionally, the right eduPersonEntitlement attribute must be set by the IdP. See The hitchhiker's guide to the TCS-personal galaxy for more details on this.
11. Have Fika!