AAI guide for SPs
Overview
This wiki page contains information about connecting services to the NI4OS AAI service in order to enable federated authentication and authorisation.
General Information
The NI4OS-Europe AAI supports both OpenID Connect (an extension to OAuth 2.0) and SAML 2.0. Regardless of which of the two protocols you are going to use, you need to provide the following information to connect your service to the NI4OS-Europe AAI:
- Name of the service
- Short description
- Privacy statement URL: The privacy policy is used to document the data collected and processed by the service. You can use the Privacy Policy template.
- Technical contact address(es)
- Security contact address(es)
- Logo URL (if available)
SAML Service Provider
To enable federated access to a web-based application, you can connect to the NI4OS AAI IdP as a SAML Service Provider (SP). Users of the application will be redirected to the NI4OS AAI in order to log in, and the NI4OS AAI 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 NI4OS AAI 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 NI4OS 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 NI4OS AAI IdP Proxy on a dedicated URL: https://aai.ni4os.eu/proxy/saml2/idp/metadata.php
Metadata
Metadata provided by your SP should contain a descriptive name of the service that your SP represents in at least English. It is recommended to also provide the name in other languages which are commonly used in the geographic scope of the deployment. The name should be placed in the <md:ServiceName> in the <md:AttributeConsumingService> container.
It is recommended that the <md:IDPSSODescriptor> element included in your SP metadata contains both an AuthnRequestsSigned and an WantAssertionsSigned attribute set to true.
Your SP metadata should also contain contact information for support and for a technical contact. The <md:EntityDescriptor> element should contain both a <md:ContactPerson> element with a contactType of "support" and a <md:ContactPerson> element with a contactType of "technical". The <md:ContactPerson> elements should contain at least one <md:EmailAddress>. The support address may be used for generic support questions about the service, while the technical contact may be contacted regarding technical interoperability problems. The technical contact must be responsible for the technical operation of the service represented by your SP.
Attributes
The NI4OS AAI IdP 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 NI4OS user ID (subject-id); this is always scoped @ni4os.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 |
|---|---|---|
| subject-id | urn:oasis:names:tc:SAML:attribute:subject-id | n472285@ni4os.eu |
| 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 | TBD |
| 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:geant:ni4os.eu:group:test-group:role=member#aai.ni4os.eu |
Attribute-based authorisation
The NI4OS AAI provides information about the authenticated user that may be used by Service Providers in order to control user access to resources. This information is provided by the NI4OS AAI IdP in the SAML attribute assertion. The table below lists the SAML attributes that are relevant for user authorisation:
| Description | SAML Attribute |
|---|---|
| Group membership/roles of the authenticated user | eduPersonEntitlement |
| Level of Assurance (LoA) | eduPersonAssurance |
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 be integrated with the NI4OS AAI using OpenID Connect (OIDC) as an alternative to the SAML2 protocol. To allow this, the NI4OS AAI IdP provides an OpenID Connect (OAuth2) API based on MITREid Connect, which has been certified by the OpenID Foundation. Interconnection with the NI4OS 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 NI4OS AAI can return OIDC Claims containing information about the authenticated user.
Client registration
Before your service can use the NI4OS OIDC Provider for user login, you must register a client in order to obtain OAuth 2.0 credentials and register one or more redirect URIs.
Obtaining OAuth 2.0 credentials
You need OAuth 2.0 credentials, including a client ID and client secret, to authenticate users through the NI4OS AAI OIDC Provider.