|
|
| (46 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| {{TOC_right}} | | {{TOC_right}} |
|
| |
|
| = Overview =
| | The documentation has moved to https://docs.egi.eu/providers/check-in/sp/. |
| | |
| This wiki page contains information about enabling federated access to EGI tools and services through the [[AAI|EGI AAI CheckIn service]]. Organisations who want to register their services with CheckIn need to fill the [https://documents.egi.eu/document/3086 form for SPs]. A PDF scansion of a printed and signed copy should be sent to operations [at] egi.eu
| |
| | |
| = Services eligible for integration =
| |
| | |
| EGI Operations, as owner of the CheckIn 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 CheckIn 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 CheckIn service. Fulfilling all the relevant EGI policies makes the service eligible in receiving attributes released by the CheckIn proxy.
| |
| | |
| == Services not federated in EGI ==
| |
| | |
| A service not part of the EGI federation can be integrated as a SP in the Checkin AAI Proxy if the institution providing the service commits to all the EGI policies that are relevant to a service provider. 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 [https://wiki.egi.eu/wiki/Policies_and_Procedures EGI Policies and procedures page] and specifically are:
| |
| # [https://documents.egi.eu/document/86 Grid Security policy]
| |
| # [https://documents.egi.eu/document/1475 Service Operations Security Policy]
| |
| # [https://documents.egi.eu/document/81 Traceability and Logging Policy]
| |
| # [https://documents.egi.eu/document/82 Security Incident Response Policy]
| |
| # [https://documents.egi.eu/document/85 Grid Policy on the Handling of User-Level Job Accounting Data]
| |
| | |
| = Service Provider integration workflow =
| |
| | |
| The integration of new SPs into the EGI CheckIn service is a two-step process:
| |
| | |
| * '''Step 1.''' Register your Service Provider and test integration with the development instance of EGI CheckIn. The development instance allows for testing authentication and authorisation without affecting the production CheckIn service. Note that the development instance is not connected to the production service and no information is shared between the two systems. However, the development instance has identical functionality, with the exception that the list of supported Identity Providers is limited. Therefore, we recommend using the EGI SSO or any of the social identity providers to test the login workflow when using the development instance.
| |
| * '''Step 2.''' Register your Service Provider with the production instance of EGI CheckIn to allow members of the EGI User Community to access your service. This requires that your service meets all the [[#Services eligible for integration|eligibility criteria]] and that integration has been thoroughly tested during Step 1.
| |
| | |
| 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.
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! 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 CheckIn IdP as a SAML Service Provider (SP). Users of the application will be redirected to CheckIn in order to log in, and CheckIn 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 Checkin 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 CheckIn 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 [https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf 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 CheckIn IdP Proxy on a dedicated URL that depends on the integration environment being used:
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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 CheckIn IdP is guaranteed to release a minimal subset of the [https://refeds.org/category/research-and-scholarship 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 (<tt>eduPersonUniqueId</tt>); this is always scoped <tt>@egi.eu</tt>
| |
| * Email address (<tt>mail</tt>)
| |
| * Display name (<tt>displayName</tt>) OR (<tt>givenName</tt> AND <tt>sn</tt>)
| |
| | |
| A more extensive list of all the attributes that may be made available to Service Providers is included in the following table:
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Attribute friendly name
| |
| ! Attribute OID
| |
| ! Example value
| |
| |-
| |
| |<tt>eduPersonUniqueId</tt>
| |
| |<tt>urn:oid:1.3.6.1.4.1.5923.1.1.1.13</tt>
| |
| |<tt>ef72285491ffe53c39b75bdcef46689f5d26ddfa00312365cc4fb5ce97e9ca87@egi.eu</tt>
| |
| |-
| |
| |<tt>mail</tt>
| |
| |<tt>urn:oid:0.9.2342.19200300.100.1.3</tt>
| |
| |<tt>john.doe@example.org</tt>
| |
| |-
| |
| |<tt>displayName</tt>
| |
| |<tt>urn:oid:2.16.840.1.113730.3.1.241</tt>
| |
| |<tt>John Doe</tt>
| |
| |-
| |
| |<tt>givenName</tt>
| |
| |<tt>urn:oid:2.5.4.42</tt>
| |
| |<tt>John</tt>
| |
| |-
| |
| |<tt>sn</tt>
| |
| |<tt>urn:oid:2.5.4.4</tt>
| |
| |<tt>Doe</tt>
| |
| |-
| |
| |<tt>eduPersonAssurance</tt>
| |
| |<tt>urn:oid:1.3.6.1.4.1.5923.1.1.1.11</tt>
| |
| |<tt>https://aai.egi.eu/LoA#Substantial</tt>
| |
| |-
| |
| |<tt>distinguishedName</tt>
| |
| |<tt>urn:oid:2.5.4.49</tt>
| |
| |<tt>/C=NL/O=Example.org/CN=John Doe</tt>
| |
| |-
| |
| |<tt>eduPersonScopedAffiliation</tt>
| |
| |<tt>urn:oid:1.3.6.1.4.1.5923.1.1.1.9</tt>
| |
| |<tt>faculty@example.org</tt>
| |
| |-
| |
| |<tt>eduPersonEntitlement</tt>
| |
| |<tt>urn:oid:1.3.6.1.4.1.5923.1.1.1.7</tt>
| |
| |<tt>urn:mace:egi.eu:www.egi.eu:wiki-editors:member@egi.eu</tt>
| |
| |}
| |
| | |
| == Attribute-based authorisation ==
| |
| | |
| EGI CheckIn 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 CheckIn IdP in the [[#Attributes|SAML attribute assertion]]. The table below lists the SAML attributes that are relevant for user authorisation:
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Description
| |
| ! SAML Attribute
| |
| |-
| |
| | [[#VO membership and role information|VO/group membership/roles of the authenticated user]]
| |
| | <tt>eduPersonEntitlement</tt>
| |
| |-
| |
| | [[#Level of Assurance|Level of Assurance (LoA)]]
| |
| | <tt>eduPersonAssurance</tt>
| |
| |}
| |
| | |
| == References ==
| |
| * [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration Shibboleth SP Configuration]
| |
| * [https://simplesamlphp.org/docs/stable/simplesamlphp-sp SimpleSAMLphp Service Provider QuickStart]
| |
| * [https://github.com/UNINETT/mod_auth_mellon Simple SAML 2.0 service provider with mod_auth_mellon Apache module]
| |
| | |
| = OpenID Connect Service Provider =
| |
| | |
| Service Providers can be integrated with EGI CheckIn using OpenID Connect (OIDC) as an alternative to the SAML2 protocol. To allow this, the EGI CheckIn IdP provides an OpenID Connect (OAuth2) API based on [https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server MITREid Connect], which has been [http://openid.net/certification/ certified by the OpenID Foundation]. Interconnection with the EGI CheckIn 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 CheckIn can return OIDC Claims containing information about the authenticated user.
| |
| | |
| == Client registration ==
| |
| | |
| Before your service can use the EGI CheckIn 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 CheckIn OIDC Provider.
| |
| | |
| You can specify the client ID and secret when creating/editing your client or let the [https://aai-dev.egi.eu/oidc/manage/admin/client/new New Client page] generate the values for you (''recommended'').
| |
| | |
| To find the ID and secret of your client, do the following:
| |
| # Select your client from the [https://aai-dev.egi.eu/oidc/manage/#admin/clients Clients page].
| |
| # Look for the '''Client ID''' in the '''Main''' tab.
| |
| # Select the '''Display/edit client secret:''' option from the '''Credentials''' tab.
| |
| | |
| === Setting a redirect URI ===
| |
| | |
| The redirect URI that you set when creating/editing your client determines where the EGI CheckIn OIDC Provider sends responses to your authentication requests.
| |
| | |
| To find the redirect URI(s) for your client, do the following:
| |
| | |
| # Open the [https://aai-dev.egi.eu/oidc/manage/#admin/clients Clients page]
| |
| # 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.
| |
| | |
| == Endpoints ==
| |
| | |
| The most important OIDC/OAuth2 endpoints are listed below:
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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 [mailto:egi-aai-checkin@lists.grnet.gr EGI CheckIn 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 CheckIn OIDC ID Tokens may contain the following fields (known as ''claims''):
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Name
| |
| ! Description
| |
| ! Example value
| |
| |-
| |
| |<tt>sub</tt>
| |
| | An identifier for the user, unique among all EGI accounts and never reused. Use <tt>sub</tt> within your application as the unique-identifier key for the user.
| |
| |<tt>ef72285491ffe53c39b75bdcef46689f5d26ddfa00312365cc4fb5ce97e9ca87@egi.eu</tt>
| |
| |-
| |
| |<tt>email</tt>
| |
| | 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 <tt>"email"</tt>).
| |
| |<tt>john.doe@example.org</tt>
| |
| |-
| |
| |<tt>name</tt>
| |
| | The user's full name, in a displayable form (in the future this will be provided only if your scope included the string <tt>"profile"</tt>).
| |
| |<tt>John Doe</tt>
| |
| |-
| |
| |<tt>given_name</tt>
| |
| | The user's first name (in the future this will be provided only if your scope included the string <tt>"profile"</tt>).
| |
| |<tt>John</tt>
| |
| |-
| |
| |<tt>family_name</tt>
| |
| | The user's last name (in the future this will be provided only if your scope included the string <tt>"profile"</tt>).
| |
| |<tt>Doe</tt>
| |
| |-
| |
| |<tt>acr</tt>
| |
| | The Authentication Context Class Reference that identifies the Level of Assurance (LoA) that the authentication performed satisfied.
| |
| |<tt>https://aai.egi.eu/LoA#Substantial</tt>
| |
| |-
| |
| |<tt>edu_person_scoped_affiliations</tt> (multivalued)
| |
| | The user's affiliation within a particular security domain (scope).
| |
| |<tt>member@example.org</tt>
| |
| |-
| |
| |<tt>edu_person_entitlements</tt> (multivalued)
| |
| | The user's entitlements expressed as group/VO membership/role information.
| |
| |<tt>urn:mace:egi.eu:www.egi.eu:wiki-editors:member@egi.eu</tt>
| |
| |}
| |
| | |
| == Claims-based authorisation ==
| |
| | |
| EGI CheckIn 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 CheckIn OIDC Provider in the form of [[#Claims|OIDC claims]]. The table below lists the claims that are relevant for user authorisation:
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Description
| |
| ! OIDC Claim
| |
| |-
| |
| | [[#VO membership and role information|VO/group membership/roles of the authenticated user]]
| |
| | <tt>edu_person_entitlements</tt>
| |
| |-
| |
| | [[#Level of Assurance|Level of Assurance (LoA)]]
| |
| | <tt>acr</tt>
| |
| |}
| |
| | |
| = 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:
| |
| <ul><li>EGI Development instance:<br>
| |
| https://masterportal-pilot.aai.egi.eu/mp-oa2-server/register<br>
| |
| <li>EGI Production instance:<br>
| |
| https://aai.egi.eu/mp-oa2-server/register
| |
| </ul>
| |
| '''''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 [mailto:egi-aai-checkin@lists.grnet.gr EGI CheckIn support].
| |
| | |
| === Detailed information ===
| |
| For further and detailed instructions on the integration flow, see the generic [https://wiki.nikhef.nl/grid/RCAuth.eu_MasterPortal_VOPortal_integration_guide RCAuth.eu MasterPortal VOPortal integration guide]
| |
| | |
| = User authorisation =
| |
| | |
| The following information about the authenticated user can be provided by EGI CheckIn in order to control user access to resources:
| |
| | |
| # VO/group membership and role information about the authenticated user
| |
| # Level of Assurance (LoA)
| |
| | |
| == VO membership and role information ==
| |
| | |
| === Background ===
| |
| Different entitlements (encoded as <tt>eduPersonEntitlement</tt> attribute values in SAML or <tt>edu_person_entitlements</tt> 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 <tt>eduPersonEntitlement</tt> for use within the EGI environment adopt the following formatting specification:
| |
| <pre>
| |
| urn:mace:egi.eu:<authority-fqdn>:[<group>[:<subgroup>:…]]:<role>@<vo>
| |
| </pre>
| |
| where:
| |
| * <tt><authority-fqdn></tt> is the FQDN of the authoritative source for the entitlement value
| |
| * <tt><vo></tt> is the name of the Virtual Organisation
| |
| * <tt><group></tt> is the name of a group in the identified <tt><vo></tt>; specifying a group is optional
| |
| * zero or more <tt><subgroup></tt> components represent the hierarchy of subgroups in the <tt><group></tt>; specifying sub-groups is optional
| |
| * the <tt><role></tt> component is scoped to the rightmost (sub)group; if no group information is specified, the role applies to the VO
| |
| | |
| === Semantics ===
| |
| Each <tt>eduPersonEntitlement</tt> 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:
| |
| <pre>
| |
| parent-group:child-group:member
| |
| </pre>
| |
| | |
| implies membership in parent-group, i.e.:
| |
| | |
| <pre>
| |
| parent-group:member
| |
| </pre>
| |
| | |
| 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:
| |
| <pre>
| |
| parent-group:child-group:manager
| |
| </pre>
| |
| | |
| implies plain membership in both <tt>child-group</tt> and <tt>parent-group</tt>, but '''NOT''':
| |
| | |
| <pre>
| |
| parent-group:manager
| |
| </pre>
| |
| | |
| == 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 <tt>eduPersonAssurance</tt> attribute and the Authentication Context Class (<tt>AuthnContextClassRef</tt>) of the SAML authentication response. EGI AAI currently distinguishes between three LoA levels, similarly to the [http://eur-lex.europa.eu/legal-content/EN/TXT/?uri=OJ:JOL_2015_235_R_0002 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
| |
| | |
| '''Important:''' A proposal for updating and refining the existing Levels of Assurance is currently a work in progress (see [[EGI-Engage:TASK JRA1.1 Proposal for Levels of Assurance|here]])
| |
The wiki is deprecated and due to be decommissioned by the end of September 2022.