AAI guide for SPs

From EGIWiki
Jump to: navigation, search

Contents


Overview

This wiki page contains information about connecting services to the EGI AAI Check-in service in order to allow user login through Check-in and to receive users' attributes.

Services eligible for integration

EGI Operations, as owner of the Check-in service, must approve every request for integration of new services with the AAI proxy. The approval (or non-approval) will be based on some pre-requisites, the relevance of the service for the EGI community 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 Check-in service

Services federated in EGI

All the services that are operated by Resource Providers federated in EGI federation and that abide to the RC OLA, and consequently to the relevant security policies of EGI, can be SP for the EGI Check-in service. Fulfilling all the relevant EGI policies makes the service eligible in receiving attributes released by the Check-in proxy.

Services not federated in EGI

A service not part of the EGI federation can be integrated as a SP in the Check-in AAI Proxy if the organisation providing the service complies with the EGI security requirements relevant to the service providers.

To assert compliance, the organisation needs to fill in the registration form for SPs. A PDF scansion 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 EGI Check-in service, you need to submit a GGUS ticket indicating your request. The responsible support unit is AAI Support. The integration follows a two-step process:

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

Protocol Development environment Production environment
SAML https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php https://aai.egi.eu/proxy/saml2/idp/metadata.php
OpenID Connect https://aai-dev.egi.eu/oidc/.well-known/openid-configuration https://aai.egi.eu/oidc/.well-known/openid-configuration

SAML Service Provider

To enable federated access to a web-based application, you can connect to the EGI Check-in IdP as a SAML Service Provider (SP). Users of the application will be redirected to Check-in in order to log in, and Check-in 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, EGI Check-in 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 Check-in 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 Check-in IdP Proxy on a dedicated URL that depends on the integration environment being used:

Development environment Production environment
https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php https://aai.egi.eu/proxy/saml2/idp/metadata.php

Attributes

The EGI Check-in 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:

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

Attribute-based authorisation

EGI Check-in 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 EGI Check-in IdP in the SAML attribute assertion. The table below lists the SAML attributes that are relevant for user authorisation:

Description SAML Attribute
VO/group membership/roles of the authenticated user eduPersonEntitlement
Level of Assurance (LoA) eduPersonAssurance

References

OpenID Connect Service Provider

Service Providers can be integrated with EGI Check-in using OpenID Connect (OIDC) as an alternative to the SAML2 protocol. To allow this, the EGI Check-in IdP provides an OpenID Connect (OAuth2) API based on MITREid Connect, which has been certified by the OpenID Foundation. Interconnection with the EGI Check-in 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, EGI Check-in can return OIDC Claims containing information about the authenticated user.

Client registration

Before your service can use the EGI Check-in OIDC Provider for user login, you must set up a client at https://aai-dev.egi.eu/oidc/manage/#admin/clients 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 EGI Check-in OIDC Provider.

You can specify the client ID and secret when creating/editing your client or let the New Client page generate the values for you (recommended).

To find the ID and secret of your client, do the following:

  1. Select your client from the Clients page.
  2. Look for the Client ID in the Main tab.
  3. Select the Display/edit client secret: option from the Credentials tab.

Setting one or more Redirection URIs

The Redirection URI(s) that you set when creating/editing your client determine where the EGI Check-in 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 in the development environment.

To find the Redirection URI(s) for your client, do the following:

  1. Open the Clients page
  2. Find the redirect URIs for your client listed under the Information column of the overview table or Edit the particular client and look for the Redirect URI(s) in the Main tab.

Setting additional information about the client

Although optional, it is strongly suggested that you add a short description and a logo for the client.

Endpoints

The most important OIDC/OAuth2 endpoints are listed below:

Endpoint Development environment Production environment
Provider configuration https://aai-dev.egi.eu/oidc/.well-known/openid-configuration https://aai.egi.eu/oidc/.well-known/openid-configuration
Client registration https://aai-dev.egi.eu/oidc Contact EGI Check-in support for registering your client
Authorisation https://aai-dev.egi.eu/oidc/authorize https://aai.egi.eu/oidc/authorize
Token https://aai-dev.egi.eu/oidc/token https://aai.egi.eu/oidc/token
User Info https://aai-dev.egi.eu/oidc/userinfo https://aai.egi.eu/oidc/userinfo
Introspection https://aai-dev.egi.eu/oidc/introspect https://aai.egi.eu/oidc/introspect

Claims

EGI Check-in OIDC ID Tokens may contain the following fields (known as claims):

Name Description Example value
sub An identifier for the user, unique among all EGI accounts and never reused. Use sub within your application as the unique-identifier key for the user. ef72285491ffe53c39b75bdcef46689f5d26ddfa00312365cc4fb5ce97e9ca87@egi.eu
email The user's email address. This may not be unique and is not suitable for use as a primary key (in the future this will be provided only if your scope included the string "email"). john.doe@example.org
name The user's full name, in a displayable form (in the future this will be provided only if your scope included the string "profile"). John Doe
given_name The user's first name (in the future this will be provided only if your scope included the string "profile"). John
family_name The user's last name (in the future this will be provided only if your scope included the string "profile"). Doe
acr The Authentication Context Class Reference that identifies the Level of Assurance (LoA) that the authentication performed satisfied. https://aai.egi.eu/LoA#Substantial
edu_person_scoped_affiliations (multivalued) The user's affiliation within a particular security domain (scope). member@example.org
edu_person_entitlements (multivalued) The user's entitlements expressed as group/VO membership/role information. urn:mace:egi.eu:www.egi.eu:wiki-editors:member@egi.eu

Claims-based authorisation

EGI Check-in 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 EGI Check-in OIDC Provider in the form of OIDC claims. The table below lists the claims that are relevant for user authorisation:

Description OIDC Claim
VO/group membership/roles of the authenticated user edu_person_entitlements
Level of Assurance (LoA) acr

Example OIDC Client

In this guide we will demonstrate how to install and configure a simple OIDC client.

Install simple-oidc-client

This guide assumes the Apache HTTP server has been installed and the document root is /var/www/html

Move to the apache document root and download and extract simple-oidc-client.zip.

Configure Client

Go to this link and login https://aai-dev.egi.eu/oidc/

Then create a new client or edit your existing client. In main tab enter a Client name and in the Redirect URI(s) insert your simple-oidc-client URL (e.g. https://example.com/simple-oidc-client/popup.html). This URL must link to popup.html which is located in simple-oidc-client directory.
Next, move to access tab and pick the scopes your service needs. Then, in Grant types check authorization code and implicit. In Response Types check code and token id_token.
Then, click save and copy your Client ID.

Configure simple-oidc-client

Now that we have everything we need, we can configure our login settings. Go to your terminal and open configuration.js with your favorite text editor. ex.

vi simple-oidc-client/configuration.js

Let’s go quickly through the settings:

You must change the followings options based on your client configuration:

An example configuration follows:

var settings = {
    title: 'Simple OIDC Client',
    authority: 'https://aai-dev.egi.eu/oidc',
    client_id: 'client',
    popup_redirect_uri: 'https://example.com/simple-oidc-client/popup.html',
    post_logout_redirect_uri: 'https://example.com/simple-oidc-client/index.html',
	
    response_type: 'token id_token',
    scope: 'openid profile email', /* add offline_access to obtain a refresh token*/
	
    debug: false,
    filterProtocolClaims: false
};

Integrating Science Gateways with RCauth for obtaining (proxy) certificates

In order for Science Gateways (VO portals) to obtain RFC proxy certificates derived from personal end-entity certificates, an EGI Science Gateway can make use of the IGTF-approved IOTA-type RCauth.eu online CA. The actual integration goes via an intermediary service, called a Master Portal.

Registering a client at the Master Portal

EGI is running two Master Portal instances, one development, one production instance. In order to register a new client go to:

NOTE: Make sure to store the client_id and client_secret in a secure place.

In order to get the client approved, send an email to the adminstrator of the EGI Master Portal using EGI Check-in support.

Detailed information

For further and detailed instructions on the integration flow, see the generic RCAuth.eu MasterPortal VOPortal integration guide

SSH key authentication for proxy retrieval

The EGI MasterPortal also allows users to authenticate using SSH key pair, in order to retrieve proxy certificates from the MasterPortal. Users need to first upload the public key via a self-service portal, https://aai.egi.eu/sshkeys/. About once a week they need to follow a web-flow to ensure a long-lived proxy certificate is present in MasterPortal, e.g. by going to https://aai.egi.eu/vo-portal/. They can then obtain a proxy certificate by doing

ssh proxy@ssh.aai.egi.eu

and storing the output in /tmp/x509up_u$(id -u)

Generic information for users on how to do this can be found at Instructions for end-users on how to use the SSH key authN for proxy retrieval.
Alternatively VO portals could implement such functionality themselves by using the API described at the Master Portal sshkey endpoint description.

User authorisation

The following information about the authenticated user can be provided by EGI Check-in in order to control user access to resources:

  1. VO/group membership and role information about the authenticated user
  2. Level of Assurance (LoA)

VO membership and role information

Background

Different entitlements (encoded as eduPersonEntitlement attribute values in SAML or edu_person_entitlements claim in OIDC) are typically used to indicate access rights to protected resources. Entitlements are multi-valued, with each value formatted as a URN.

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:

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:

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:

Important: A proposal for updating and refining the existing Levels of Assurance is currently a work in progress (see here)

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Print/export