AAI guide for SPs

Overview

This wiki page contains information about enabling federated access to EGI tools and services through the EGI AAI Proxy.

SAML Service Provider

To enable federated access to a web-based application, you can to connect to the EGI AAI IdP Proxy as a SAML Service Provider (SP). Users of the application will be redirected to the Proxy to log in, and the Proxy can authenticate them using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN or Social Providers. Once the user is authenticated, the EGI AAI Proxy will return a SAML assertion to the application containing information about the authenticated user.

Metadata registration

SAML authentication relies on the use of metadata. Both parties (you as a SP and the EGI AAI IdP) need to exchange metadata in order to know and trust each other. The metadata include information such as the location of the service endpoints that need to be invoked, as well as the certificates that will be used to sign SAML messages. The format of the exchanged metadata should be based on the XML-based SAML 2.0 specification. Usually, you will not need to manually create such an XML document, as this is automatically generated by all major SAML 2.0 SP software solutions (e.g., Shibboleth, SimpleSAMLphp, and mod_auth_mellon). It is important that you serve your metadata over HTTPS using a browser-friendly SSL certificate, i.e. issued by a trusted certificate authority.

You can get the metadata of the EGI IdP Proxy on a dedicated URL:

https://aai.egi.eu/proxy/saml2/idp/metadata.php

Attribute release

The EGI AAI IdP Proxy is guaranteed to release a minimal subset of the REFEDS R&S attribute bundle to connected Service Providers without administrative involvement, subject to user consent. The following attributes constitute a minimal subset of the R&S attribute bundle:

• Persistent, non-reassignable, non-targeted, opaque, globally unique EGI user ID (eduPersonUniqueId); this is always scoped @egi.eu
• Email address (mail)
• Display name (displayName) OR (givenName AND sn)

A more extensive list of all the attributes that may be made available to Service Providers is included in the following table:

Attribute friendly name	Attribute OID	Example value
eduPersonUniqueId	urn:oid:1.3.6.1.4.1.5923.1.1.1.13	ef72285491ffe53c39b75bdcef46689f5d26ddfa00312365cc4fb5ce97e9ca87@egi.eu
mail	urn:oid:0.9.2342.19200300.100.1.3	john.doe@example.org
displayName	urn:oid:2.16.840.1.113730.3.1.241	John Doe
givenName	urn:oid:2.5.4.42	John
sn	urn:oid:2.5.4.4	Doe
eduPersonAssurance	urn:oid:1.3.6.1.4.1.5923.1.1.1.11	https://aai.egi.eu/LoA#Substantial
distinguishedName	urn:oid:2.5.4.49	/C=NL/O=Example.org/CN=John Doe
eduPersonScopedAffiliation	urn:oid:1.3.6.1.4.1.5923.1.1.1.9	faculty@example.org
eduPersonEntitlement	urn:oid:1.3.6.1.4.1.5923.1.1.1.7	urn:mace:egi.eu:www.egi.eu:wiki-editors:member@egi.eu

Authorisation

The EGI AAI IdP Proxy provides information about the authenticated user that may be used by Service Providers in order to control user access to resources. Such information includes:

1. VO/EGI membership/roles of the authenticated user (eduPersonEntitlement SAML attribute)
2. Level of Assurance (LoA)

VO membership and role information

Background

The eduPerson object specification defines the eduPersonEntitlement attribute In order to control access to resources. This is a multi-valued attribute, with each value formatted as a URI (either URN or URL) to indicate a set of rights to specific resources based on an agreement across the relevant communities. eduPersonEntitlement attributes are typically used to assert privileges maintained centrally or remotely rather than within local application-specific user databases.

Syntax

Values for eduPersonEntitlement for use within the EGI environment adopt the following formatting specification:

urn:mace:egi.eu:<authority-fqdn>:[<group>[:<subgroup>:…]]:<role>@<vo>

where:

• <authority-fqdn> is the FQDN of the authoritative source for the entitlement value
• <vo> is the name of the Virtual Organisation
• <group> is the name of a group in the identified <vo>; specifying a group is optional
• zero or more <subgroup> components represent the hierarchy of subgroups in the <group>; specifying sub-groups is optional
• the <role> component is scoped to the rightmost (sub)group; if no group information is specified, the role applies to the VO

Semantics

Each eduPersonEntitlement attribute value represents a particular position of the user within a VO. A user may be member or hold more specific roles within the groups associated to a VO. Groups are organised in a tree structure, meaning that a group may have subgroups, which in turn may have subgroups, etc.

This hierarchical structure implies that if someone is member of a subgroup, then they are also member of the parent group. For example:

parent-group:child-group:member

implies membership in parent-group, i.e.:

parent-group:member

Ownership of any role always implies the member role for that particular (sub)group. However, holding a more specific role (i.e. one other than member) in a subgroup does not imply the same role in the parent group. For example:

parent-group:child-group:manager

implies plain membership in both child-group and parent-group, but NOT:

parent-group:manager

Level of Assurance

Based on the authentication method selected by the user, the EGI proxy assigns a Level of Assurance (LoA), which is conveyed to the SP through both the eduPersonAssurance attribute and the Authentication Context Class (AuthnContextClassRef) of the SAML authentication response. EGI AAI currently distinguishes between three LoA levels, similarly to the eID Assurance Framework (eIDAF). Each level is represented by a URI as follows:

• Low: Authentication through a social identity provider or other low identity assurance provider: https://aai.egi.eu/LoA#Low
• Substantial: Password/X.509 authentication at the user's home IdP: https://aai.egi.eu/LoA#Substantial
• High: Substantial + multi-factor authn (not yet supported, TBD): https://aai.egi.eu/LoA#High

Some EGI SPs have been configured to provide limited access (or not to accept at all) credentials with the Low LoA.

Note: When logging in through the EGI SSO IdP, the LoA is determined based on the selected authentication mechanism as follows:

• Username/password credentials → Low
• X.509 certification → Substantial

TODO: A document describing each LoA will soon be made available.

References

• Shibboleth SP Configuration
• SimpleSAMLphp Service Provider QuickStart
• Simple SAML 2.0 service provider with mod_auth_mellon Apache module

OpenID Connect Service Provider

Service Providers can connect to the EGI AAI using OpenID Connect (OIDC) as an alternative to the SAML2 protocol. To allow this, the EGI AAI IdP Proxy provides an OpenID Connect (OAuth2) API based on MITREid Connect, which has been certified by the OpenID Foundation. Interconnection with the EGI AAI OIDC Provider allows users to sign in using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN or Social Providers. Once the user has signed in, the EGI AAI Proxy can return OIDC Claims containing information about the authenticated user.

Client registration

Before your service can use the EGI AAI OIDC IdP for user login, you must set up a client at https://aai.egi.eu/oidc in order to obtain OAuth 2.0 credentials and register one or more redirect URIs.

Endpoints

The EGI AAI OIDC Provider configuration is available at https://aai.egi.eu/oidc/.well-known/openid-configuration

The most important OIDC/OAuth2 endpoints are listed below:

Endpoint	URL
Client registration	https://aai.egi.eu/oidc
Authorisation	https://aai.egi.eu/oidc/authorize
Token	https://aai.egi.eu/oidc/token
User Info	https://aai.egi.eu/oidc/userinfo

Claims

The following claims are supported by the EGI AAI OIDC IdP:

Name	Example value
sub	ef72285491ffe53c39b75bdcef46689f5d26ddfa00312365cc4fb5ce97e9ca87@egi.eu
email	john.doe@example.org
name	John Doe
given_name	John
family_name	Doe
acr	https://aai.egi.eu/LoA#Substantial
edu_person_scoped_affiliations (multivalued)	faculty@example.org
edu_person_entitlements (multivalued)	urn:mace:egi.eu:www.egi.eu:wiki-editors:member@egi.eu