Guidelines for Services#

Organisational#

Services in Helmholtz AAI need to specify which Virtual Organisations they want to support. Thereby, they delegate the right to specify members to the VO Administrator.

Services can specify requirements on the quality of the user identities (assurance), i.e. whether they need to have a working contract with their home institution, or whether a social identity is good enough.

Note#

Please inform the HIFIS support about which VOs you support. We will keep track of that information and document it as soon as available. An overview list of supported VOs can be found here.


Policies#

For policy reasons we need several points:

  • Service Security Contact: this contact MUST be able to provide information about user logins to the security people in case of a security incident.
  • Privacy Policy: This is a legal requirement. Luckily we do have a GDPR compliant PP template into which you only have to insert the specifics of your service.
  • Acceptable Use Policy: The AUP Template is what the users will have to “accept” before entering a VO. This may or may not be acceptable for services at your research centre. It is up to you to make sure. If it is not acceptable and you need to specify a custom Service AUP, it is up to you to ensure that the users of your service are aware of and agree to abide by it. (Note: for KIT we are in the process of getting the permission to use the general AUP as an alternative to our “IUK Ordnung”.)
  • Finally, you MAY provide a Service Access Policy (no specific format required) where you can specify user requirements for accessing the service, such as supported VOs and assurance levels. Please make sure you are following the guidelines when expressing requirements for assurance. If you need additional user attributes besides those available, you may also specify them here, but it is up to you to negotiate any bilateral agreements that might be required.

Additionally, you need to accept and abide by the following policies:


Technical#

Helmholtz AAI is capable of supporting OpenID Connect (OIDC) and SAML. Here we only describe OIDC. If you are sure you need SAML, please contact Marcus Hardt and Sander Apweiler.

OIDC#

For OIDC you need to register a client in the => unity production instance. You need to click on the top right “No account/sign up”. Here’s some explanation for a few fields (Note: mouse-over also displays help):

  • User Name is the OIDC client_id (you can choose it)
  • Password is the OIDC client_secret (you choose it)
  • Email Address is an email address for contacting the admin of the service
  • Service Security Contact is the security responsible of the service. This may be additional people, for example in a hosted VM setup
  • Site Security Contactis your computer centre security contact. Typically your CERT.
  • Service PP URL: This is your Privacy Policy (PP). Required by law. Find a PP template here
  • The well_known configuration of login is here:
https://login.helmholtz.de/oauth2/.well-known/openid-configuration

Service Specific Configuration#

Provided Attributes from the Helmholtz AAI:#

Please note, that the service MUST only request attributes that are necessary for running it. Anything in addition is a violation to the GDPR and may have legal consequences. User will see which attributes are going to be released to the service.

SAML:#

Name Format
common name urn:oid:2.5.4.3
email urn:oid:0.9.2342.19200300.100.1.3
eduPersonUniqueId urn:oid:1.3.6.1.4.1.5923.1.1.1.13
eduPersonScopedAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.9
eduPersonPrincipalName urn:oid:1.3.6.1.4.1.5923.1.1.1.6
givenName urn:oid:2.5.4.42
sn urn:oid:2.5.4.4
eduPersonEntitlement urn:oid:1.3.6.1.4.1.5923.1.1.1.7

OAuth2/OIDC:#

scope Attribute
openid
email email, email_verified
profile name, eduperson_entitlement, given_name, family_name, preferred_username
credentials ssh_key, preferred_username
eduperson_scoped_affiliation eduperson_scoped_affiliation
eduperson_entitlement eduperson_entitlement
eduperson_principal_name eduperson_principal_name
eduperson_unique_id eduperson_unique_id
eduperson_assurance eduperson_assurance
display_name display_name
sn sn
single-logout

Unique identifier in Helmholtz AAI:#

The Helmholtz identifier offers an unique identifier for every user, which allows to connect the accounts of the user on different services. This is released as eduPersonUniqueId (SAML: urn:oid:1.3.6.1.4.1.5923.1.1.1.13 / OIDC: eduperson_unique_id). This ID is created by the Helmholtz AAI itself. The Helmholtz AAI does not reuse some identifier from the centres Identity providers for several reasons:

  • Email is no identifier because it is not unique across time and will be reused if a user left the organisation
  • eduPersonPrincipalName is no good identifier because centres may use the email address as eduPersonUniqueId too.
  • Sent identifiers by centres are not used because some centres does not sent persistent identifiers but transient identifiers. Those are only unique for user, identity provider and service provider. If a user logs into two different services the IDs, released to this services, are not equal.

In case of SAML the identifier is the first part of the eduPersonUniqueId. In case of the OAuth/OIDC the eduPersonUniqueId is sub(without dashes)@iss.

Group membership information:#

The Helmholtz AAI releases group membership information according to AARC-G002 guideline. The information is released as eduPersonEntitlement in the following format:

<NAMESPACE>:group:GROUPNAME[:SUBGROUPNAME]#<AUTHORITY>

The first part, inclusive the namespace, is the unique name of the group information. The authority displays which provider accounted the user to the group. Group membership information may be granted by different authorities. The user can review the group memberships of groups which are managed within the Helmholtz AAI in their profile in the home endpoint. In this case only the GROUPNAME is displayed. The created eduPersonEntitlement values are released together with information, received during the login with the centres identity provider.

Resource capability information:#

The Helmholtz AAI releases resource capability information according to AARC-G027 guideline. The information is released as eduPersonEntitlement in the following format:

<NAMESPACE>:res:RESOURCENAME[:PERMISSION]#<AUTHORITY>

The first part, including the namespace, is the unique name of the resources where capabilities are granted. The authority displays which provider granted the permission to use the resource. Resource capabilities may be granted by different authorities. The created eduPersonEntitlement values are released together with information, received during the login with the centres identity provider.