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.

Difference between revisions of "AAI guide for SPs"

From EGIWiki
Jump to navigation Jump to search
imported>Nliam
(Added link to EGI docs site)
Tag: Replaced
 
(6 intermediate revisions by 4 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 connecting services to the [[AAI|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 [https://documents.egi.eu/document/3086 registration form for SPs]. A PDF scan of a printed and signed copy should be sent to [mailto:operations@egi.eu?Subject=EGI%20Check-in%20service%20provider%20registration%20form 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 [https://wiki.egi.eu/wiki/Policies_and_Procedures EGI Policies and procedures page] and specifically are:
# [https://documents.egi.eu/document/3015 e-Infrastructure 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/2732 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 [[GGUS:AAI_SUPPORT_FAQ|AAI Support]]. The integration follows a two-step process:
 
* '''Step 1.''' Register your Service Provider and test integration with the '''demo''' instance of EGI Check-in. The demo instance allows for testing authentication and authorisation without affecting the production Check-in service. Note that while the demo instance has identical functionality to the production instance, no information is shared between the two systems.
** You can also test new features of Check-in that are not available in production yet, by registering your Service Provider and testing integration with the '''development''' instance of Check-in. As with the demo instance, the development instance allows for testing authentication and authorisation without affecting the production Check-in service. '''NB: the list of supported Identity Providers in the development instance 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 Check-in 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
! Demo environment
! Production environment
|-
| SAML
| https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php
| https://aai-demo.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-demo.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 [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 Check-in IdP 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/saml2/idp/metadata.php
| https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php
| https://aai.egi.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 <tt><md:ServiceName></tt> in the <tt><md:AttributeConsumingService></tt> container.
 
It is recommended that the <tt><md:IDPSSODescriptor></tt> element included in your SP metadata contains both an <tt>AuthnRequestsSigned</tt> and an <tt>WantAssertionsSigned</tt> attribute set to <tt>true</tt>.
 
Your SP metadata should also contain contact information for support and for a technical contact. The <tt><md:EntityDescriptor></tt> element should contain both a <tt><md:ContactPerson></tt> element with a <tt>contactType</tt> of "<tt>support</tt>" and a <tt><md:ContactPerson></tt> element with a <tt>contactType</tt> of "<tt>technical</tt>". The <tt><md:ContactPerson></tt> elements should contain at least one <tt><md:EmailAddress></tt>. 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 EGI Check-in 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:group:vo.test.egi.eu:role=member#aai.egi.eu</tt> <br/> <tt>urn:mace:egi.eu:aai.egi.eu:member@vo.test.egi.eu</tt> ''(WARNING this format will be deprecated)''
|}
 
== 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 [[#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 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 [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 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 [https://aai-dev.egi.eu/oidc/manage/user/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/user/clients Clients page].
# Look for the '''Client ID''' in the '''Main''' tab.
# 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 <code>https</code> scheme; the use of <code>http</code> Redirection URIs is only allowed in the development environment.
 
To find the Redirection URI(s) for your client, do the following:
 
# Open the [https://aai-dev.egi.eu/oidc/manage/user/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.
 
=== Setting additional information about the client ===
It is strongly suggested that you add a short '''description''' and a '''logo''' for the client. Lastly, you need to set the email addresses of one or more contacts.
 
== Claims ==
 
The EGI Check-in 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 EGI Check-in 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 EGI Check-in UserInfo Endpoint:
 
{| class="wikitable"
|-
! Scope name
! Claim name
! Claim description
! Example claim value
|-
|<tt>openid</tt>
|
|
|
|-
|
|<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>profile</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>preferred_username</tt>
| The username by which the user wishes to be referred to. The RP MUST NOT rely upon this value being unique.
|<tt>jdoe</tt>
|-
|<tt>email</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>refeds_edu</tt> (deprecated)
|
|
|
|-
|
|<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>eduperson_assurance</tt>
| The Level of Assurance (LoA) that the authentication performed satisfied.
|<tt>https://aai.egi.eu/LoA#Substantial</tt>
|-
|
|<tt>eduperson_scoped_affiliation</tt> (multivalued) <br/> <tt>edu_person_scoped_affiliations</tt> (deprecated)
| The user's affiliation within a particular security domain (scope).
|<tt>member@example.org</tt>
|-
|
|<tt>eduperson_entitlement</tt> (multivalued) <br/> <tt>edu_person_entitlements</tt> (deprecated)
| The user's entitlements expressed as group/VO membership/role information.
|<tt>urn:mace:egi.eu:group:vo.test.egi.eu:role=member#aai.egi.eu</tt> <br/> <tt>urn:mace:egi.eu:aai.egi.eu:member@vo.test.egi.eu</tt> ''(WARNING this format will be deprecated)''
|-
|<tt>eduperson_scoped_affiliation</tt>
|
|
|
|-
|
|<tt>eduperson_scoped_affiliation</tt> (multivalued) <br/> <tt>edu_person_scoped_affiliations</tt> (deprecated)
| The user's entitlements expressed as group/VO membership/role information.
|<tt>urn:mace:egi.eu:group:vo.test.egi.eu:role=member#aai.egi.eu</tt> <br/> <tt>urn:mace:egi.eu:aai.egi.eu:member@vo.test.egi.eu</tt> ''(WARNING this format will be deprecated)''
|-
|<tt>eduperson_entitlement</tt>
|
|
|
|-
|
|<tt>eduperson_entitlement</tt> (multivalued) <br/> <tt>edu_person_entitlements</tt> (deprecated)
| The user's affiliation within a particular security domain (scope).
|<tt>member@example.org</tt>
|}
 
== 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.
* 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:
{| class="wikitable"
!Endpoint
!Development environment
!Demo environment
!Production environment
|-
|Provider configuration
|https://aai-dev.egi.eu/oidc/.well-known/openid-configuration
|https://aai-demo.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 Check-in support] for registering your client''
|''Contact [mailto:egi-aai-checkin@lists.grnet.gr EGI Check-in support] for registering your client''
|-
|Authorisation
|https://aai-dev.egi.eu/oidc/authorize
|https://aai-demo.egi.eu/oidc/authorize
|https://aai.egi.eu/oidc/authorize
|-
|Token
|https://aai-dev.egi.eu/oidc/token
|https://aai-demo.egi.eu/oidc/token
|https://aai.egi.eu/oidc/token
|-
|User Info
|https://aai-dev.egi.eu/oidc/userinfo
|https://aai-demo.egi.eu/oidc/userinfo
|https://aai.egi.eu/oidc/userinfo
|-
|Introspection
|https://aai-dev.egi.eu/oidc/introspect
|https://aai-demo.egi.eu/oidc/introspect
|https://aai.egi.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:
 
* <code>client_id</code>: id of the client that ask for authentication to the Authorization Server.
* <code>redirect_uri</code>: URI to which the response will be sent.
* <code>scope</code>: A list of attributes that the application requires.
* <code>state</code>: Opaque value used to maintain state between the request and the callback.
* <code>response_type</code>: value that determines the authorization processing flow to be used.
 
# For '''Authorization Code''' grant set <code>response_type=code</code>. This way the response will include an authorization code.
# For '''Implicit''' grant set <code>response_type=token</code>. 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.
 
Depending on the grant type, the following parameters are required:
 
==== Authorization Code ====
 
    {| class="wikitable"
    !Parameter
    !Presence
    !Values
    |-
    |<code>grant_type</code>
    |Required
    |<code>authorization_code</code>
    |-
    |<code>code</code>
    |Required
    |The value of the code in the response from authorization endpoint.
    |-
    |<code>redirect_uri</code>
    |Required
    |<code>URI to which the response will be sent (must be the same as the request to authorization endpoint)</code>
    |}
 
==== Refresh request ====
 
The following request allows obtaining an access token from a refresh token using the <code>grant_type</code> value <code>refresh_token</code>:
 
    {| class="wikitable"
    !Parameter
    !Presence
    !Values
    |-
    |<code>client_id</code>
    |Required
    |The identifier of the client
    |-
    |<code>client_secret</code>
    |Required
    |The secret value of the client.
    |-
    |<code>grant_type</code>
    |Required
    |<code>refresh_token</code>
    |-
    |<code>refresh_token</code>
    |Required
    |<code>The value of the refresh token</code>
    |-
    |scope
    |Required
    |This parameter should contain openid at least
    |}
 
'''Example request'''
 
    <code>
        curl -X POST -u "${client_id}":"${client_secret}" \
            -d 'client_id={myClientID}' \
            -d 'client_secret={myClientSecret}' \
            -d 'grant_type=refresh_token' \
            -d 'refresh_token=${myRefreshToken}' \
            -d 'scope=openid%20email%20profile' \
            'https://aai-dev.egi.eu/oidc/token' | python -m json.tool;
    </code>
 
'''Example response'''
 
    <code>
        {
            "access_token": "eyJraWQiOiJvaWRjIiwiYWx...",
            "expires_in": 3599,
            "id_token": "eyJraWQiOiJvaWRjIiwiYW...",
            "refresh_token": "eyJhbGciOiJub25...",
            "scope": "openid profile email",
            "token_type": "Bearer"
        }
    </code>
 
==== Token Exchange ====
 
To get a token from client B using a token issued for client A, the parameters of the request are:
 
    {| class="wikitable"
    !Parameter
    !Presence
    !Values
    |-
    |grant_type
    |Required
    |<code>urn:ietf:params:oauth:grant-type:token-exchange</code>
    |-
    |audience
    |Optional
    |Define the logical name of the service that the token will be used for
    |-
    |subject_token
    |Required
    |The value of the access token
    |-
    |subject_token_type
    |Required
    |<code>urn:ietf:params:oauth:token-type:access_token</code>
    (because this feature accepts access tokens only)
    |-
    |scope
    |Optional
    |Define one or more scopes that are contained in the original token; otherwise all scopes will be selected
    |}
 
'''Example request'''
 
    <code>
        curl -X POST -u "${client_B_id}":"${client_B_secret}" \
            -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
            -d 'audience=tokenExchange' \
            -d 'subject_token=${access_token_A} \
            -d 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
            -d 'scope=openid%20profile%20offline_access' \
            'http://aai.egi.eu/oidc/token' | python -m json.tool;
    </code>
 
'''Example response'''
 
    <code>
        {
            "access_token": "eyJraWQiOiJvaWRjIiwiYWxnIjoiUl...",
            "expires_in": 3599, "id_token": "eyJraWQiOiJvaWRjIiwiYWxnIjoiUl...",
            "refresh_token": "eyJhbGciOiJub25lIn0.eyJleHAiO...",
            "scope": "openid profile offline_access",
            "token_type": "Bearer"
        }
    </code>
 
==== Device Code ====
 
The device code flow enables OAuth clients on (input-constrained) devices to obtain user authorization for accessing protected resources without using an on-device user-agent, provided that they have an Internet connection.
    <ol>
        <li>'''Device Authorization Request'''
        <br>The client initiates the authorization flow by requesting a set of verification codes from the authorization server by making an HTTP "POST" request to the device authorization endpoint.The client constructs the request with the following parameters:
 
        {| class="wikitable"
        !Parameter
        !Presence
        !Values
        |-
        |client_id
        |Required
        |The identifier of the client
        |-
        |scope
        |Optional
        |Define one or more scopes that are contained in the original token; otherwise all scopes will be selected
        |}
 
'''Example request'''
 
        <code>
            curl -X POST "https://aai-dev.egi.eu/oidc/devicecode" \
                -H "Content-Type: application/x-www-form-urlencoded" \
                -d "client_id={myClientID}" \
                -d "&scope=openid%20email%20profile" | python -m json.tool
        </code>
 
'''Example response'''
 
        <code>
            {
                "device_code": "c4341bd6-5e82-4f9c-9f6f-5842409d48db",
                "expires_in": 600,
                "user_code": "IEJSJB",
                "verification_uri": "https://aai-dev.egi.eu/oidc/device"
            }
        </code>
        </li>
        <li>'''User Interaction'''
        <br>After receiving a successful Authorization Response, the client displays or otherwise communicates the "user_code" and the "verification_uri" to the end user and instructs them to visit the URI in a user agent on a secondary device (for example, in a browser on their mobile phone), and enter the user code.
        </li>
        <li>'''Device Access Token Request'''
        <br>After displaying instructions to the user, the client makes an Access Token Request to the token endpoint. The request contains the following parameters:
        {| class="wikitable"
        !Parameter
        !Presence
        !Values
        |-
        |grant_type
        |Required
        |<code>urn:ietf:params:oauth:grant-type:device_code</code>
        |-
        |device_code
        |Required
        |The device verification code, "device_code" from the Device Authorization Response
        |-
        |client_id
        |Required
        |The identifier of the client
        |-
        |client_secret
        |Required
        |The secret value of the client
        |-
        |scope
        |Optional
        |Define one or more scopes that are contained in the original token; otherwise all scopes will be selected
        |}
 
'''Example request'''
 
        <code>
            curl -X POST "https://aai-dev.egi.eu/oidc/token" \
                -H "Content-Type: application/x-www-form-urlencoded" \
                -d "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
                -d "&device_code={myDeviceCode}" \
                -d "&client_id={myClientID}" \
                -d "&client_secret={myClientSecret}" \
                -d "&scope=openid%20profile" | python -m json.tool
        </code>
 
'''Example response'''
 
        <code>
            {
                "access_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhZG1pbiIs...",
                "expires_in": 3599,
                "id_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI5MDM0Mi...",
                "scope": "openid profile",
                "token_type": "Bearer"
            }
        </code>
        </li>
    </ol>
 
== 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 [[#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>
|}
 
== Example OIDC Client ==
In this guide we will demonstrate how to install and configure a [https://github.com/rciam/simple-oidc-client simple OIDC client].
 
=== Install simple-oidc-client ===
This guide assumes the Apache HTTP server has been installed and the document root is <code>/var/www/html</code>
 
Move to the apache document root and download and extract [https://github.com/rciam/simple-oidc-client/releases/download/v1.0.0/simple-oidc-client.zip 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 <code>main</code> tab enter a <code>Client name</code> and in the <code>Redirect URI(s)</code> 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.<br/>
Next, move to <code>access</code> tab and pick the <code>scopes</code> your service needs. Then, in <code>Grant types</code> check <code>authorization code</code> and <code>implicit</code>. In <code>Response Types</code> check <code>code</code> and <code>token id_token</code>.<br/>
Then, click save and copy your <code>Client ID</code>.
 
=== Configure simple-oidc-client ===
Now that we have everything we need, we can configure our login settings.
Go to your terminal and open <code>configuration.js</code> with your favorite text editor.
ex.
<pre>
vi simple-oidc-client/configuration.js
</pre>
 
Let’s go quickly through the settings:
 
* <code>title</code> is the title on the navigation bar.
* <code>authority</code> is the base URL of our IdentityServer instance. This will allow oidc-client to query the metadata endpoint so it can validate the tokens.
* <code>client_id</code> is the id of the client we want to use when hitting the authorization endpoint.
* <code>popup_redirect_uri</code> is the redirect URL used when using the signinPopup method. If you prefer not having a popup and redirecting the user in the main window, you can use the redirect_uri property and the signinRedirect method.
* <code>post_logout_redirect_uri</code> is the redirect URL used when using the signoutRedirect method.
* <code>response_type</code> defines in our case that we only expect an identity token back.
* <code>scope</code> defines the scopes the application asks for.
* <code>debug</code> displays user data.
* <code>filterProtocolClaims</code> indicates to oidc-client if it has to filter some OIDC protocol claims from the response: nonce, at_hash, iat, nbf, exp, aud, iss and idp.
 
You must change the followings options based on your client configuration:
* <code>authority</code> (issuer)
* <code>client_id</code>
* <code>scope</code>
 
An example configuration follows:
<pre>
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
};
</pre>
 
= 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 Check-in support].
 
=== Detailed information ===
For further and detailed instructions on the integration flow, see the generic [https://wiki.nikhef.nl/grid/RCauth.eu_and_MasterPortal_VOPortal_integration_guide 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 [https://wiki.nikhef.nl/grid/RCauth.eu_and_MasterPortal_SSH_Key_Portal Instructions for end-users on how to use the SSH key authN for proxy retrieval].<BR>
Alternatively VO portals could implement such functionality themselves by using the API described at the [https://wiki.nikhef.nl/grid/Master_Portal_sshkey_endpoint 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:
 
# VO/group membership and role information about the authenticated user
# Level of Assurance (LoA)
 
== VO/group membership and role information ==
 
=== Background ===
VO/group membership and role information is encoded in entitlements (<tt>eduPersonEntitlement</tt> attribute values in SAML or <tt>edu_person_entitlements</tt> claim in OIDC). These entitlements are typically used to indicate access rights to protected resources. Entitlements are multi-valued, with each value formatted as a URN.
 
=== Syntax ===
An entitlement value expressing group membership and role information has the following syntax (components enclosed in square brackets are OPTIONAL): 
<pre>
urn:mace:egi.eu:group:<GROUP>[:<SUBGROUP>*]][:role=<ROLE>]#<GROUP-AUTHORITY>
</pre>
where:
* <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:'''
<pre>
urn:mace:egi.eu:group:fedcloud.egi.eu:role=vm_operator#aai.egi.eu
</pre>
 
=== Old Syntax (will be deprecated in a next release) ===
An entitlement value expressing group membership and role information has the following syntax (components enclosed in square brackets are OPTIONAL): 
<pre>
urn:mace:egi.eu:<GROUP-AUTHORITY>:[<GROUP>[:<SUBGROUP>:…]]:<ROLE>@<VO>
</pre>
 
'''Example:'''
<pre>
urn:mace:egi.eu:aai.egi.eu:vm_operator@fedcloud.egi.eu
</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]])

Latest revision as of 01:01, 5 November 2020


The documentation has moved to https://docs.egi.eu/providers/check-in/sp/.