|
|
| Line 1: |
Line 1: |
| {{TOC_right}} | | {{TOC_right}} |
|
| |
|
| = Overview =
| | The documentation has moved to https://docs.egi.eu/providers/check-in/idp/. |
| | |
| This wiki page contains information about integrating your identity provider with the [[AAI | EGI AAI Proxy]] in order to allow users in your community to access EGI tools and services.
| |
| | |
| Organisations who want to register their IDP in Check-in needs to fill this [https://documents.egi.eu/document/3086 form] in case the IdP is not publishing R&S and Sirtfi compliance in eduGAIN. A PDF scansion of a printed and signed copy should be sent to operations [at] egi.eu
| |
| | |
| = Identity Provider integration workflow =
| |
| | |
| To integrate your Identity Provider with the EGI Check-in service, you need to submit a [[GGUS]] ticket indicating your request. The responsible support unit is [[GGUS:AAI_SUPPORT_FAQ|AAI Support]]. The integration follows a two-step process:
| |
| | |
| * '''Step 1.''' Register your Identity Provider and test integration with the development instance of EGI Check-in. The development instance allows for testing authentication and authorisation to EGI services and resources without affecting the production environment of EGI. Note that the development instance is not connected to the production service and no information is shared between the two systems.
| |
| * '''Step 2.''' Register your Identity Provider with the production instance of EGI Check-in to allow members of your Community to access production EGI services and resources protected by Check-in. This requires that your Identity Provider meets all the [https://documents.egi.eu/document/3086 policy requirements] 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
| |
| ! Demo environment
| |
| ! Production environment
| |
| |-
| |
| | SAML
| |
| | https://aai-dev.egi.eu/proxy/module.php/saml/sp/metadata.php/sso
| |
| | https://aai-demo.egi.eu/proxy/module.php/saml/sp/metadata.php/sso
| |
| | https://aai.egi.eu/proxy/module.php/saml/sp/metadata.php/sso
| |
| |-
| |
| | OpenID Connect
| |
| | See [[#Client_registration|client registration]]
| |
| | See [[#Client_registration|client registration]]
| |
| | See [[#Client_registration|client registration]]
| |
| |}
| |
| | |
| = General requirements for integrating identity providers =
| |
| | |
| An institution or a community may connect their IdP with Check-in to allow their users to access EGI services, or any other services that have enabled Check-in as an authentication provider. This section presents the general requirements for integrating an IdP with EGI Check-in, while protocol-specific instructions are provided in the sections that follow.
| |
| | |
| == Attribute release requirements ==
| |
| | |
| As a bare minimum, the IdP of a user’s Home Organisation or Community is expected to release a non-reassignable identifier that uniquely identifies the user within the scope of that organisation or community. The unique identifier must be accompanied with a minimum set of attributes which the Check-in Service Provider Proxy will attempt to retrieve from the user’s IdP. If this is not possible, the missing user attributes will be acquired and verified through the user registration process with the EGI Account Registry. The following table describes the data requested from the user's Home Organisation, which are communicated to the Check-in SP as either SAML attributes or OIDC claims, depending on the protocol supported by the authenticating IdP.
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Description
| |
| ! Notes
| |
| |-
| |
| | At least one of the following unique user identifiers:
| |
| # pseudonymous, non-targeted identifier;
| |
| # name-based, non-targeted identifier;
| |
| # pseudonymous, targeted identifier
| |
| |
| |
| |-
| |
| | Preferred name for display purposes
| |
| | For example to be used in a greeting or a descriptive listing
| |
| |-
| |
| | First name
| |
| |
| |
| |-
| |
| | Surname
| |
| |
| |
| |-
| |
| | Email address
| |
| |
| |
| |-
| |
| | Affiliation within Home Organisation or Community
| |
| |
| |
| |-
| |
| | Group(s)/role(s) within Home Organisation or Community
| |
| | To be released '''only''' if relevant for accessing EGI federated resources
| |
| |}
| |
| | |
| Note that the above set of requested attributes, particularly the identifier, name, email and affiliation information, complies with the [https://refeds.org/category/research-and-scholarship REFEDS R&S attribute bundle].
| |
| | |
| Information about group membership and role information released by your IdP should follow the URN scheme below (see also [https://aarc-community.org/guidelines/aarc-g002 AARC-G002]):
| |
| | |
| <pre>
| |
| <NAMESPACE>:group:<GROUP>[:<SUBGROUP>*]][:role=<ROLE>]#<GROUP-AUTHORITY>
| |
| </pre>
| |
| where:
| |
| * <tt><NAMESPACE></tt> is in the form of <tt>urn:<NID>:<DELEGATED-NAMESPACE>[:<SUBNAMESPACE>*]</tt>, where
| |
| ** <tt><NID></tt> is the namespace identifier associated with a URN namespace registered with [https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml IANA], as per RFC8141, ensuring global uniqueness. Implementers can and should use one of the existing registered URN namespaces, such as <tt>urn:geant</tt> [https://www.geant.org/Services/Trust_identity_and_security/Pages/NamespaceRegistry.aspx] and <tt>urn:mace</tt> [https://www.internet2.edu/products-services/trust-identity/mace-registries/urnmace-namespace/];
| |
| ** <tt><DELEGATED-NAMESPACE></tt> is a URN sub-namespace delegated from one of the IANA registered NIDs
| |
| to an organisation representing the e-infrastructure, research infrastructure or research collaboration.
| |
| * <tt><GROUP></tt> is the name of a VO, research collaboration or a top level arbitrary group. <GROUP> names are unique within the <tt>urn:mace:egi.eu:group</tt> namespace;
| |
| * zero or more <tt><SUBGROUP></tt> components represent the hierarchy of subgroups in the <tt><GROUP></tt>; specifying sub-groups is optional
| |
| * the optional <tt><ROLE></tt> component is scoped to the rightmost (sub)group; if no group information is specified, the role applies to the VO
| |
| * <tt><GROUP-AUTHORITY></tt> is a non-empty string that indicates the authoritative source for the entitlement value. For example, it can be the FQDN of the group management system that is responsible for the identified group membership information
| |
| | |
| '''Example entitlement values expressing VO/group membership and role information:'''
| |
| <pre>
| |
| urn:geant:dariah.eu:group:egi-interop:role=member#aaiproxy.de.dariah.eu"
| |
| urn:geant:dariah.eu:group:egi-interop:role=vm_operator#aaiproxy.de.dariah.eu”
| |
| </pre>
| |
| | |
| == Operational and security requirements ==
| |
| | |
| The IdP needs to comply with additional requirements to achieve a higher level of assurance and allow its users to gain access to a wider set of EGI services.
| |
| A first group of additional requirements are defined by the [https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf Sirtfi framework v1.0]. Adherence to these requirements can be asserted either by publishing Sirtfi compliance in the eduGAIN metadata or by declaring it in this [https://documents.egi.eu/document/3086 form]. These requirements are in the areas of operational security, incident response, traceability and IdPs and users responsibility.
| |
| | |
| == Branding requirements ==
| |
| | |
| Check-in provides a central Discovery Service (or "Where Are You From" - WAYF) page where users in your Home Organisation or Community will be automatically redirected when necessary to select to authenticate at your IdP. You can provide us with a logo of your Organisation or Community (in high-res png or preferably in svg format) to include a dedicated login button that will allow users to easily identify your IdP.
| |
| | |
| = SAML Identity Provider =
| |
| | |
| To allow users in your community to sign into federated EGI applications, you need to connect to the EGI AAI SP Proxy as a SAML Identity Provider (IdP). Users of the application will be redirected to the central Discovery Service page of the EGI AAI Proxy where they will able to select to authenticate at your IdP. Once the user is authenticated, the EGI AAI Proxy will return a SAML assertion to the application containing the information returned by your IdP about the authenticated user.
| |
| | |
| == Metadata registration ==
| |
| | |
| SAML authentication relies on the use of metadata. Both parties (you as an IdP and the EGI AAI SP) 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 IdP software solutions (e.g., Shibboleth, SimpleSAMLphp). It is important that you serve your metadata over HTTPS using a browser-friendly SSL certificate, i.e. issued by a trusted certificate authority.
| |
| | |
| To exchange metadata, please send an email including the following information:
| |
| # '''entityID'''
| |
| # '''Metadata URL'''
| |
| | |
| Depending on the software you are using, the authoritative XML metadata URL for your IdP might be in the following form:
| |
| | |
| * <code>https://your.idp.example.eu/idp/shibboleth</code> (Shibboleth)
| |
| * <code>https://your.idp.example.eu/simplesaml/module.php/saml2/idp/metadata.php</code> (SimpleSAMLphp)
| |
| | |
| Note that if your IdP is part of a federation, then it would be preferred to send us the URL to a signed federation metadata aggregate. We can then cherry pick the appropriate entityID from that.
| |
| | |
| You can get the metadata of the EGI Check-in SP Proxy on a dedicated URL that depends on the integration environment being used:
| |
| {| class="wikitable"
| |
| |-
| |
| ! Development environment
| |
| ! Demo environment
| |
| ! Production environment
| |
| |-
| |
| | https://aai-dev.egi.eu/proxy/module.php/saml/sp/metadata.php/sso
| |
| | https://aai-demo.egi.eu/proxy/module.php/saml/sp/metadata.php/sso
| |
| | https://aai.egi.eu/proxy/module.php/saml/sp/metadata.php/sso
| |
| |}
| |
| | |
| For the production environment, it is recommended that you get the metadata for the EGI Check-in SP (entityID: <code>https://aai.egi.eu/proxy/module.php/saml/sp/metadata.php/sso</code>) from a signed eduGAIN metadata aggregate. For example, the following aggregates are provided by GRNET:
| |
| * [https://md.aai.grnet.gr/aggregates/grnet-metadata.xml GRNET federation's metadata]
| |
| * [https://md.aai.grnet.gr/feeds/edugain-sp-samlmd.xml eduGAIN SP metadata]
| |
| | |
| == Attribute release ==
| |
| | |
| The SAML based Identity Provider of your Home Organisation or Community is expected to release a non-reassignable identifier that uniquely identifies the user within the scope of that organisation or community, along with a set of additional information as described in the following table (see also [[#Attribute_release_requirements|general attribute release requirements]]):
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Description
| |
| ! SAML attribute
| |
| |-
| |
| | At least one of the following unique user identifiers:
| |
| # pseudonymous, non-targeted identifier;
| |
| # name-based, non-targeted identifier;
| |
| # pseudonymous, targeted identifier
| |
| |
| |
| # <tt>SubjectID</tt> (public) or <tt>eduPersonUniqueId</tt>
| |
| # <tt>eduPersonPrincipalName</tt>
| |
| # <tt>SubjectID</tt> (pairwise) or <tt>eduPersonTargetedID</tt> or SAML persistent identifier
| |
| |-
| |
| | Preferred name for display purposes
| |
| | <tt>displayName</tt>
| |
| |-
| |
| | First name
| |
| | <tt>givenName</tt>
| |
| |-
| |
| | Surname
| |
| | <tt>sn</tt>
| |
| |-
| |
| | Email address
| |
| | <tt>mail</tt>
| |
| |-
| |
| | Affiliation within Home Organisation or Community
| |
| | <tt>eduPersonScopedAffiliation</tt>
| |
| |-
| |
| | Group(s)/role(s) within Home Organisation or Community
| |
| | <tt>eduPersonEntitlement</tt>
| |
| |}
| |
| | |
| = OpenID Connect Identity Provider =
| |
| | |
| Users in your community can sign into federated EGI applications through the Check-in service using your OpenID Connect or OAuth 2.0 based Identity Provider.
| |
| | |
| == Client registration ==
| |
| | |
| To enable your OIDC Identity Provider for user login, Check-in needs to be registered as a client in order to obtain OAuth 2.0 credentials, such as a client ID and client secret, and to register one or more redirect URIs. Once Check-in is registered as a client, your users will be redirected to the central Discovery Service page of Check-in when logging into EGI federated applications, where they will able to select to authenticate at your IdP. Once the user is authenticated, Check-in will be responsible for communicating the information returned by your IdP about the authenticated user to the connected application. Depending on the protocol, this information will be expressed through a SAML assertion, a set of OIDC claims or a (proxy) X.509 certificate.
| |
| | |
| == Provider configuration ==
| |
| | |
| Check-in needs to obtain your OpenID Provider's configuration information, including the location of the Authorisation, Token and UserInfo endpoints. Your OpenID Provider is expected to make a JSON document available at the path formed by concatenating the string <tt>/.well-known/openid-configuration</tt> to the Issuer, following the [https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig OpenID Connect Discovery 1.0 specification].
| |
| | |
| == Attribute release ==
| |
| | |
| The OpenID Connect or OAuth 2.0 based Identity Provider of your Home Organisation or Community is expected to release a non-reassignable identifier that uniquely identifies the user within the scope of that organisation or community, along with a set of additional information as described in the following table (see also [[#Attribute_release_requirements|general attribute release requirements]]):
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Description
| |
| ! OIDC claim
| |
| |-
| |
| | At least one of the following unique user identifiers:
| |
| # pseudonymous, non-targeted identifier;
| |
| # name-based, non-targeted identifier;
| |
| # pseudonymous, targeted identifier
| |
| |
| |
| # <tt>sub</tt> (public)
| |
| # N/A
| |
| # <tt>sub</tt> (pairwise)
| |
| |-
| |
| | Preferred name for display purposes
| |
| | <tt>name</tt>
| |
| |-
| |
| | First name
| |
| | <tt>given_name</tt>
| |
| |-
| |
| | Surname
| |
| | <tt>family_name</tt>
| |
| |-
| |
| | Email address
| |
| | <tt>email</tt>
| |
| |-
| |
| | Affiliation within Home Organisation or Community
| |
| | <tt>eduperson_scoped_affiliation</tt>
| |
| |-
| |
| | Group(s)/role(s) within Home Organisation or Community
| |
| | <tt>eduperson_entitlement</tt>
| |
| |}
| |
| | |
| = Integration success stories =
| |
| * [https://wiki.egi.eu/wiki/EGI_AAI_integration_with_ELIXIR_AAI EGI AAI integration with ELIXIR]
| |
The wiki is deprecated and due to be decommissioned by the end of September 2022.