Attributes in Helmholtz AAI¶

Consumed Attributes from identity providers (IdP)¶

The Helmholtz AAI consumes only a small set of attributes from identity providers. The attributes, that are generally requested are those specified in the => REFEDS Research and Scholarship entity category. If the identity provider releases those attributes, the login for users works out of the box.

In addition, the assurance of the user will be described, using the => REFEDS Assurance Framework.

REFEDS Research and Scholarship¶

Also called R and S, or R&S.

You should read the original link (it’s not long). In short, R&S makes sure that the identiy provider will release these attributes.

Mandatory:
- shared user identifier
  - eduPersonPrincipalName (if non-reassigned)
  - eduPersonPrincipalName + eduPersonTargetedID
- person name:
  - givenName + sn
- email address:
  - email
Optional:
- affiliation
  - eduPersonScopedAffiliation

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:¶

Attribute	Format	Optional	Modifiable by user	Description	Example
`common name`	`urn:oid:2.5.4.3`	no	no	The full name of the user. Build by the provided `given_name` and `family_name` information.	Jane Doe
`email`	`urn:oid:0.9.2342.19200300.100.1.3`	no	no	The email address of the user, provided by the home organisation. In case of social Identity providers provided by the user.	dummy@email.org
`voPersonId`	`urn:oid:1.3.6.1.4.1.25178.4.1.6`	no	no	The unique identifier of the user at Helmholtz ID	aed850a702e540d5961ba0e7dac83af9@login.helmholtz.de
`eduPersonScopedAffiliation`	`urn:oid:1.3.6.1.4.1.5923.1.1.1.9`	no	no	The affiliation of the user at one of the Helmholtz organisations. The mapping of the translation is based on the affiliation of the home organisation. Further information about this mapping are available here.	affiliate@login.helmholtz.de
`eduPersonPrincipalName`	`urn:oid:1.3.6.1.4.1.5923.1.1.1.6`	yes	no	eduPersonPrincipleName from the home organisation.
`givenName`	`urn:oid:2.5.4.42`	no	no	The givenname of the user, provided by the home organisation. In case of social Identity providers provided by the user.	Jane
`sn`	`urn:oid:2.5.4.4`	no	no	The familyname of the user, provided by the home organisation. In case of social Identity providers provided by the user.	Doe
`eduPersonEntitlement`	`urn:oid:1.3.6.1.4.1.5923.1.1.1.7`	yes	no	Permissions and group membership information of the user. The information are from home organisations and from Helmholtz ID. Find more information about Group membership information and Resource capabilities	`urn:geant:helmholtz.de:group:Helmholtz-member#login.helmholtz.de`, `urn:geant:helmholtz.de:res:HELIPORT#login.helmholtz.de`

OAuth2/OIDC:¶

Attribte	Optional	Type	Modifiable by user	Description	Example	Request via scope
`email`	no	`string`	no	The email address of the user, provided by the home organisation. In case of social Identity providers provided by the user.	dummy@email.org	`email`
`email_verified`	no	`boolean`	no	Whether the email address was verified or not.	True	`email`
`name`	no	`string`	no	The full name of the user. Build by the provided `given_name` and `family_name` information.	Jane Doe	`profile`
`given_name`	no	`string`	no	The givenname of the user, provided by the home organisation. In case of social Identity providers provided by the user.	Jane	`profile`
`family_name`	no	`string`	no	The familyname of the user, provided by the home organisation. In case of social Identity providers provided by the user.	Doe	`profile`
`preferred_username`	yes	`string`	yes	The preferred username is preset with the first part of the email address and can be updated by the user.		`profile` or `credentials`
`ssh_key`	yes	`string`	yes	The public SSH key of the user.		`credentials`
`entitlements`	yes	`string` or `list of strings`	no	Permissions and group membership information of the user. The information are from home organisations and from Helmholtz ID. Find more information about Group membership information and Resource capabilities	`urn:geant:helmholtz.de:group:Helmholtz-member#login.helmholtz.de`, `urn:geant:helmholtz.de:res:HELIPORT#login.helmholtz.de`	`entitlements`
`eduperson_scoped_affiliation`	no	`string` or `list of strings`	no	The affiliation of the user at one of the Helmholtz organisations. The mapping of the translation is based on the affiliation of the home organisation. Further information about this mapping are available here.	affiliate@login.helmholtz.de	`eduperson_scoped_affiliation`
`voPersonId`	no	`string`	no	The unique identifier of the user at Helmholtz ID	aed850a702e540d5961ba0e7dac83af9@login.helmholtz.de	`voperson_id`

Scopes¶

In OAuth2/OIDC several attributes may be grouped by so called ‘scopes’. The client requests a set of scopes and received the corresponding list of attributes for the requested scopes. The scopes below are available at Helmholtz ID.

scope	Attribute	Description
`openid`		Scope to signal the usage of OIDC on top of OAuth2.
`email`	`email`, `email_verified`	Email address of the user and it’s validation status.
`profile`	`name`, `eduperson_entitlement`, `given_name`, `family_name`, `preferred_username`	Basic information of the user like the name in different formats.
`credentials`	`ssh_key`, `preferred_username`	SSH key and preferred username of the user.
`eduperson_scoped_affiliation`	`eduperson_scoped_affiliation`	Affiliation of the user at Helmholtz ID, based on the affiliation at the home organisation. Further information about this mapping are available here.
`voperson_external_affiliation`	`voperson_external_affiliation`	Affiliation of the user at the home organisation/upstream identity provider.
`entitlements`	`entitlements`	Permissions and group membership information of the user.
`eduperson_principal_name`	`eduperson_principal_name`	The eduPersonPrincipleName from the home organisation of the user.
`voperson_id`	`voperson_id`	Unique identifier of the user.
`eduperson_assurance`	`eduperson_assurance`	Asurance information of the user.
`display_name`	`display_name`	Displayname of the user.
`sn`	`sn`	Familyname of the user.
`single-logout`		Scope to trigger the single logout of the user, when revoking the tokens.
`offline_access`		Scope to fetch refresh tokens. It is mandatory to send `consent=prompt` as additional query parameter.

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 voPersonId (SAML: urn:oid:1.3.6.1.4.1.25178.4.1.6 / OIDC: voperson_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 voPersonId. In case of the OAuth/OIDC the voPersonId 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.