Alert.png The wiki is deprecated and due to be decommissioned by the end of September 2022.
The content is being migrated to other supports, new updates will be ignored and lost.
If needed you can get in touch with EGI SDIS team using operations @ egi.eu.

EOSC Portal AAI guide for SPs

From EGIWiki
Revision as of 11:16, 30 April 2021 by Nliam (talk | contribs) (Add endpoints for demo environment)
Jump to navigation Jump to search


Overview

This wiki page contains information about connecting services to the EOSC Portal AAI service in order to allow user authentication using the academic/social account of choice, including eduGAIN and Research Community AAIs.

Services eligible for integration

EGI Operations, as owner of the EOSC Portal AAI service, must approve every request for integration of new services with the EOSC Portal AAI. The approval (or non-approval) will be based on some pre-requisites, the relevance of the service for the EOSC Portal and the available resources to support the integration. The pre-requisites are described in the following sections.

EGI at any time can prevent a service provider to access the EOSC Portal AAI service

To assert compliance, the organisation needs to fill in the registration form for SPs. A PDF scan of a printed and signed copy should be sent to operations (at) egi.eu.

By accepting the policies a service provider assures that they will operate the service in good faith, without deliberately exposing the user to security risks, without claiming intellectual property on the data owned by the user, and protecting sensitive data generated by the interaction of the user with the service.

The policies that the service provider will have to accept are available in this page EGI Policies and procedures page and specifically are:

  1. e-Infrastructure Security Policy
  2. Service Operations Security Policy
  3. Traceability and Logging Policy
  4. Security Incident Response Policy
  5. Policy on the Processing of Personal Data

Service Provider integration workflow

To integrate your Service Provider with the EOSC Portal AAI service, you need to submit a GGUS ticket indicating your request. The responsible support unit is Check-in (AAI).

The most important URLs for enabling the integration are listed in the table below but more information can be found in the protocol-specific sections that follow.

Protocol Endpoint (Demo environment) Endpoint (Production environment)
SAML https://aai-demo.eosc-portal.eu/proxy/saml2/idp/metadata.php https://aai.eosc-portal.eu/proxy/saml2/idp/metadata.php
OpenID Connect https://aai-demo.eosc-portal.eu/oidc/.well-known/openid-configuration https://aai.eosc-portal.eu/oidc/.well-known/openid-configuration

SAML Service Provider

To enable federated access to a web-based application, you can connect to the EOSC Portal AAI IdP as a SAML Service Provider (SP). Users of your application will be redirected to the EOSC Portal in order to log in, and the EOSC Portal AAI can authenticate them using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN, Research Community AAIs or Social Providers. Once the user is authenticated, the EOSC Portal will return a SAML assertion to your 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 EOSC Portal 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 retrieve the metadata of the EOSC Portal IdP Proxy on a dedicated URL that depends on the integration environment being used:

Metadata (Demo environment) Metadata (Production environment)
https://aai-demo.eosc-portal.eu/proxy/saml2/idp/metadata.php https://aai.eosc-portal.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 EOSC Portal AAI IdP is guaranteed to release a minimal subset of the REFEDS R&S attribute bundle as described in the following table:

Attribute friendly name Attribute OID Example value Availability
eduPersonUniqueId urn:oid:1.3.6.1.4.1.5923.1.1.1.13 xyz@example.org Always
mail urn:oid:0.9.2342.19200300.100.1.3 john.doe@example.org Always
displayName urn:oid:2.16.840.1.113730.3.1.241 John Doe Always
givenName urn:oid:2.5.4.42 John Always
sn urn:oid:2.5.4.4 Doe Always
eduPersonScopedAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.9 faculty@example.org Optional (Only when released by the user's identity provider)
eduPersonEntitlement urn:oid:1.3.6.1.4.1.5923.1.1.1.7 urn:mace:example.org:group:group.example.org:role=member#example.org Optional (Only when released by the user's identity provider)

References

OpenID Connect Service Provider

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

Client registration

Before your service can use the EOSC Portal OIDC Provider for user login, you need to register an OIDC client by submitting a GGUS ticket indicating your request. The responsible support unit is Check-in (AAI).

Please, include the following information in your ticket:

  1. Client name
  2. Client description (max 100 words)
  3. One or more Redirection URIs. The Redirection URI(s) determine where the EOSC Portal AAI OIDC Provider sends responses to your authentication requests. Note that the Redirection URI MUST use the https scheme; the use of http Redirection URIs is only allowed for testing purposes.
  4. Client logo URL
  5. email addresses of one or more contacts of the following types:
    1. administrative
    2. technical
    3. support
    4. security
  6. privacy policy URL

As a result of the client registration you will obtain OAuth 2.0 credentials, which typically include a client ID and client secret.

Claims

The EOSC Portal AAI UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns specific information about the authenticated End-User as Claim Values. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. The scopes associated with the Access Token used to access the EOSC Portal AAI UserInfo Endpoint will determine what Claims will be released. These Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.

The following scope values can be used to request Claims from the EOSC Portal AAI UserInfo Endpoint:

Scope name Claim name Claim description Example claim value Availability
openid
sub An identifier for the user which is globally unique and not reassignable. Use sub within your application as the unique-identifier key for the user. xyz@example.org Always
profile
name The user's full name, in a displayable form. John Doe Always
given_name The user's first name. John Always
family_name The user's last name. Doe Always
email
email The user's email address. This may not be unique and is not suitable for use as a primary key. john.doe@example.org Always
eduperson_scoped_affiliation
eduperson_scoped_affiliation (multivalued) The user's affiliation within a particular security domain (scope). member@example.org Optional (Only when released by the user's identity provider)
eduperson_entitlement
eduperson_entitlement (multivalued) The user's entitlements, typically expressed as capabilities on resources or, alternatively, as group membership and/or role information urn:mace:example.org:group:group.example.org:role=member#example.org Optional (Only when released by the user's identity provider)

Grant Types

Check-in supports the following OpenID Connect/OAuth2 grant types:

  • Authorization Code: used by Web Apps executing on a server.
  • Implicit: used by JavaScript-centric apps (Single Page Applications) executing on the user's browser (not recommended).
  • Token Exchange: used by clients to request and obtain security tokens in support of delegated access to resources.
  • Device Code: used by devices that lack a browser to perform a user-agent based OAuth flow.

Endpoints

The most important OIDC/OAuth2 endpoints are listed below:

Name Endpoint (Demo environment) Endpoint (Production environment)
Provider configuration https://aai-demo.eosc-portal.eu/oidc/.well-known/openid-configuration https://aai.eosc-portal.eu/oidc/.well-known/openid-configuration
Client registration Contact EOSC Portal support for registering your client Contact EOSC Portal support for registering your client
Authorisation https://aai-demo.eosc-portal.eu/oidc/authorize https://aai.eosc-portal.eu/oidc/authorize
Token https://aai-demo.eosc-portal.eu/oidc/token https://aai.eosc-portal.eu/oidc/token
User Info https://aai-demo.eosc-portal.eu/oidc/userinfo https://aai.eosc-portal.eu/oidc/userinfo
Introspection https://aai-demo.eosc-portal.eu/oidc/introspect https://aai.eosc-portal.eu/oidc/introspect

Authorization Endpoint

The Authorization Endpoint performs Authentication of the End-User. This is done by sending the User Agent to the Authorization Server's Authorization Endpoint for Authentication and Authorization, using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect.

The request parameters of the Authorization endpoint are:

  • client_id: id of the client that ask for authentication to the Authorization Server.
  • redirect_uri: URI to which the response will be sent.
  • scope: A list of attributes that the application requires.
  • state: Opaque value used to maintain state between the request and the callback.
  • response_type: value that determines the authorization processing flow to be used.
  1. For Authorization Code grant set response_type=code. This way the response will include an authorization code.
  2. For Implicit grant set response_type=token. This way the response will include both an Access Token and an ID Token.

Token Endpoint

To obtain an Access Token, an ID Token, and optionally a Refresh Token, the Client sends a Token Request to the Token Endpoint.