This page contains information about connecting services to EGI Check-in in order to allow user login through Check-in and to receive users' attributes. Check-in is connected to a wide range of academic and social Identity Providers that users can choose from in order to access your service.
EGI Operations, as owner of the Check-in service, must approve every request for integration of new services with Check-in. The approval (or non-approval) is based on some prerequisites, the relevance of the service for the EGI community and the available resources to support the integration. The prerequisites are described in the following sections.
EGI at any time can prevent a service provider to access the Check-in service
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 connected with Check-in. Fulfilling all the relevant EGI policies makes the service eligible in receiving attributes released by Check-in.
A service not part of the EGI federation can be integrated with Check-in if the organisation providing the service complies with the EGI security requirements relevant to the service providers.
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 the EGI Policies and procedures page and specifically are:
To integrate your Service Provider with the EGI Check-in service, you need to create a registration request using the EGI Federation Registry Portal. You can also use the Federation Registry portal to request the reconfiguration or deregistration of an existing deployed service. Service registration requests typically require approval by an administrator. Please refer to the Federation Registry Documentation for more information.
The integration follows a two-step process:
EGI Check-in supports two authentication and authorisation protocols that you can choose from:
Service providers should ensure that a proper authorisation model is put in place: if low assurance accounts, like those coming from social media identity providers, are granted access without any vetting, it may lead to an abuse of their service.
Regardless of which of the two protocols you are going to use, you need to provide the following information to connect your service to EGI Check-in:
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 | Production environment |
---|---|
SAML | https://aai.egi.eu/proxy/saml2/idp/metadata.php |
OpenID Connect | https://aai.egi.eu/oidc/.well-known/openid-configuration |
Protocol | Demo environment |
---|---|
SAML | https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php |
OpenID Connect | https://aai-demo.egi.eu/oidc/.well-known/openid-configuration |
Protocol | Development environment |
---|---|
SAML | https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php |
OpenID Connect | https://aai-dev.egi.eu/oidc/.well-known/openid-configuration |
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.
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:
Production environment |
---|
https://aai.egi.eu/proxy/saml2/idp/metadata.php |
Demo environment |
---|
https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php |
Development environment |
---|
https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php |
To register your SAML SP, you must submit a service registration request at Federation Registry. Your request should include the general information about your service (see General Information) and the SP’s metadata and entity ID.
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.
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:
voPersonID
). For users whose community identity is managed by Check-in,
this identifier is of the form <uniqueID>@egi.eu
. The <uniqueID>
portion
is an opaque identifier issued by Check-in.mail
)displayName
) OR (givenName
AND sn
)A more extensive list of all the attributes that may be made available to Service Providers is included in the User Attribute section.
As mentioned in the General Information, omitting authorisation checks may lead to abuse of the service.
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 |
Capabilities | eduPersonEntitlement |
GOCDB roles | eduPersonEntitlement |
Identity Assurance | eduPersonAssurance |
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.
Before your service can use the EGI Check-in OIDC Provider for user login, you must submit a service registration request using Federation Registry in order to obtain OAuth 2.0 credentials. The client configuration should include the general information about your service, as described in General Information section.
You need OAuth 2.0 credentials, which typically include 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 them being automatically generated during registration (recommended).
To find the ID and secret of your client, do the following:
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:
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.
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:
Scope | Claims |
---|---|
openid | sub |
profile |
|
email |
|
aarc |
|
eduperson_entitlement | eduperson_entitlement |
eduperson_scoped_affiliation | eduperson_scoped_affiliation |
voperson_id | voperson_id |
A more extensive list of all the attributes that may be made available to Service Providers is included in the User Attribute section.
Check-in supports the following OpenID Connect/OAuth2 grant types:
The most important OIDC/OAuth2 endpoints are listed below:
Endpoints | Production environment |
---|---|
Provider configuration | https://aai.egi.eu/oidc/.well-known/openid-configuration |
Issuer | https://aai.egi.eu/oidc/ |
Authorisation | https://aai.egi.eu/oidc/authorize |
Token | https://aai.egi.eu/oidc/token |
Device Code | https://aai.egi.eu/oidc/devicecode |
JSON Web Key(JWK) | https://aai.egi.eu/oidc/jwk |
User Info | https://aai.egi.eu/oidc/userinfo |
Introspection | https://aai.egi.eu/oidc/introspect |
Logout | https://aai.egi.eu/oidc/saml/logout |
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. For Authorization Code grant set response_type=code
. This way the
response will include an authorization code.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:
Parameter | Presence | Values |
---|---|---|
grant_type | Required | authorization_code |
code | Required | The value of the code in the response from authorization endpoint. |
redirect_uri | Required | URI to which the response will be sent (must be the same as the request to authorization endpoint) |
The Proof Key for Code Exchange (PKCE, pronounced pixie) extension
(RFC 7636) describes a technique for
public clients (clients without client_secret
) to mitigate the threat of
having the authorization code intercepted. The technique involves the client
first creating a secret, and then using that secret again when exchanging the
authorization code for an access token. This way if the code is intercepted, it
will not be useful since the token request relies on the initial secret.
To enable PKCE you need to go to the Manage Services Page and create/edit a client. In “Protocol” tab under “Token Endpoint Authentication Method” select “No authentication” and in “Crypto” tab under “Proof Key for Code Exchange (PKCE) Code Challenge Method” select “SHA-256 hash algorithm”.
Because the PKCE-enhanced Authorization Code Flow builds upon the standard Authorization Code Flow, the steps are very similar.
First, the client creates and records a secret named the code_verifier
. The
code_verifier
is a high-entropy cryptographic random STRING using the
unreserved characters [A-Z] / [a-z] / [0-9] / “-” / “.” / “_” / “~”, with a
minimum length of 43 characters and a maximum length of 128 characters. Then the
client creates a code_challenge
derived from the code_verifier
by using one
of the following transformations on the code verifier:
plain
code_challenge = code_verifierS256
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))If the client is capable of using S256
, it MUST use S256
. Clients are
permitted to use plain
only if they cannot support S256
for some technical
reason.
Then the code_challenge
is sent in the Authorization Request along with the
transformation method (code_challenge_method
).
Example request:
GET "${AUTHORISATION_ENDPOINT}?
client_id=${CLIENT_ID}
&scope=openid%20profile%20email
&redirect_uri=${REDIRECT_URI}
&response_type=code
&code_challenge=${CODE_CHALLENGE}
&code_challenge_method=S256"
The Authorization Endpoint responds as usual but records code_challenge
and
the code_challenge_method
.
Example response:
HTTP/1.1 302 Found
Location: ${REDIRECT_URI}?
code=fgtLHT
The client then sends the authorization code in the Access Token Request as
usual but includes the code_verifier
secret generated in the first request.
Example request:
curl -X POST "${TOKEN_ENDPOINT}" \
-d "grant_type=authorization_code" \
-d "code=${CODE}" \
-d "client_id=${CLIENT_ID}" \
-d "redirect_uri=${REDIRECT_URI}" \
-d "code_verifier=${CODE_VERIFIER}" | python -m json.tool
The authorization server transforms code_verifier
and compares it to
code_challenge
from the first request. Access is denied if they are not equal.
Example response:
{
"access_token": "eyJraWQiOiJvaWRjIiwiYWxnIjoiUlMyNTYifQ...",
"expires_in": 3599,
"id_token": "eyJraWQiOiJvaWRjIiwiYWxnIjoiUlMyNTYifQ...",
"scope": "openid email profile",
"token_type": "Bearer"
}
The following request allows obtaining an access token from a refresh token
using the grant_type
value refresh_token
:
Parameter | Presence | Values |
---|---|---|
client_id | Required | The identifier of the client. |
client_secret | Required | The secret value of the client. |
grant_type | Required | refresh_token |
refresh_token | Required | The value of the refresh token |
scope | Required | This parameter should contain openid at least |
Example request:
curl -X POST "${TOKEN_ENDPOINT}" \
-u "${CLIENT_ID}":"${CLIENT_SECRET}" \
-d "grant_type=refresh_token" \
-d "refresh_token=${REFRESH_TOKEN}" \
-d "scope=openid%20email%20profile" | python -m json.tool;
Example response:
{
"access_token": "eyJraWQiOiJvaWRjIiwiYWx...",
"expires_in": 3599,
"id_token": "eyJraWQiOiJvaWRjIiwiYW...",
"refresh_token": "eyJhbGciOiJub25...",
"scope": "openid profile email",
"token_type": "Bearer"
}
To combine the refresh token grant type with PKCE you need to make the following request:
curl -X POST "${TOKEN_ENDPOINT}" \
-d "client_id=${CLIENT_ID}" \
-d "grant_type=refresh_token" \
-d "refresh_token=${REFRESH_TOKEN}" \
-d "scope=openid%20email%20profile" | python -m json.tool;
To get a token from client B using a token issued for client A, the parameters of the request are:
Parameter | Presence | Values |
---|---|---|
grant_type | Required | urn:ietf:params:oauth:grant-type:token-exchange |
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 | urn:ietf:params:oauth:token-type:access_token (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:
curl -X POST "${TOKEN_ENDPOINT}" \
-u "${CLIENT_B_ID}":"${CLIENT_B_SECRET}" \
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=${ACCESS_TOKEN_A}" \
-d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
-d "scope=openid%20profile%20offline_access" | python -m json.tool;
Example response:
{
"access_token": "eyJraWQiOiJvaWRjIiwiYWxnIjoiUl...",
"expires_in": 3599,
"id_token": "eyJraWQiOiJvaWRjIiwiYWxnIjoiUl...",
"refresh_token": "eyJhbGciOiJub25lIn0.eyJleHAiO...",
"scope": "openid profile offline_access",
"token_type": "Bearer"
}
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.
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:
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:
curl -X POST "${DEVICE_CODE_ENDPOINT}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=${CLIENT_ID}" \
-d "scope=openid%20email%20profile" | python -m json.tool
Example response:
{
"device_code": "c4341bd6-5e82-4f9c-9f6f-5842409d48db",
"expires_in": 600,
"user_code": "IEJSJB",
"verification_uri": "https://aai.egi.eu/oidc/device"
}
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.
After displaying instructions to the user, the client makes an Access Token Request to the token endpoint. The request contains the following parameters:
Parameter | Presence | Values |
---|---|---|
grant_type | Required | urn:ietf:params:oauth:grant-type:device_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:
curl -X POST "${TOKEN_ENDPOINT}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-d "device_code=${DEVICE_CODE}" \
-d "client_id=${CLIENT_ID}" \
-d "client_secret=${CLIENT_SECRET}" \
-d "scope=openid%20profile" | python -m json.tool
Example response:
{
"access_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhZG1pbiIs...",
"expires_in": 3599,
"id_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI5MDM0Mi...",
"scope": "openid profile",
"token_type": "Bearer"
}
To combine Device Code flow with PKCE you need to make the following requests:
1 - Device Authorization Request:
curl -X POST "${DEVICE_CODE_ENDPOINT}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=${CLIENT_ID}" \
-d "scope=openid%20email%20profile" \
-d "code_challenge=${CODE_CHALLENGE}" \
-d "code_challenge_method=S256" | python -m json.tool
2 - Device Access Token Request
curl -X POST "${TOKEN_ENDPOINT}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-d "device_code=${DEVICE_CODE}" \
-d "client_id=${CLIENT_ID}" \
-d "code_verifier=${CODE_VERIFIER}" | python -m json.tool
As mentioned in the General Information, omitting authorisation checks may lead to abuse of the service.
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 | eduperson_entitlement |
Capabilities | eduperson_entitlement |
GOCDB roles | eduperson_entitlement |
Identity Assurance | eduperson_assurance |
In this guide we will demonstrate how to install and configure a 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-php.tar.gz.
Login to the EGI Federation Registry
Then create a new service or edit your existing service. In General
tab fill
all the required fields. For Integration Environment
select Demo
. In
Protocol Specific
tab select as Protocol the OIDC Service
and then in the
Redirect URI(s)
insert your simple-oidc-client-php URL (e.g.
http://localhost/simple-oidc-client-php/refreshtoken.php
). This URL must link
to refreshtoken.php
which is located in simple-oidc-client-php directory.
Next, in Scope
select the scopes that your service needs. Then, submit the
form and and self approve it. Finally you should get a pair of Client ID
and
Client Secret
.
Now that you have everything you need, you can configure your login settings. Go
to your terminal and open config.php
with your favorite text editor.
Example:
vi simple-oidc-client-php/config.php
Let’s go quickly through the settings:
title
required, the title on the navigation barimg
required, the source of the logoscope_info
optional, a message that informs the user for the application
requirementsissuer
required, the base URL of our IdentityServer instance. This will
allow oidc-client to query the metadata endpoint so it can validate the tokensclient_id
required, the ID of the client we want to use when hitting the
authorization endpointclient_secret
optional, a value the offers better security to the message
flowpkceCodeChallengeMethod
optional, a string that defines the code challenge
method for PKCE. Choose between plain
or S256
.redirect_url
required, the redirect URL where the client and the browser
agree to send and receive correspondingly the codescopesDefine
required, defines the scopes the client supportsrefresh_token_note
optional, info for the refresh tokenaccess_token_note
optional, info for the access tokenmanage_token_note
optional, message the informs the user where can manage
his tokensmanageTokens
optional, URL of the manage tokens servicesessionName
required, define the name of the cookie sessionsessionLifetime
required, define the duration of the session. This must be
equal to the validity time of the access token.You must change the followings options based on your Service configuration you setup earlier:
issuer
client_id
client_secret
redirect_url
scopesDefine
sessionName
(based on the installation path of the portal)An example configuration follows:
<?php
// index.php interface configuration
$title = "Generate Tokens";
$img = "https://clickhelp.co/images/feeds/blog/2016.05/keys.jpg";
$scope_info = "This service requires the following permissions for your account:";
// Client configuration
$issuer = "https://aai-demo.egi.eu/oidc/";
$client_id = "CHANGE_ME";
$client_secret = "CHANGE_ME"; // comment if you are using PKCE
// $pkceCodeChallengeMethod = "S256"; // uncomment to use PKCE
$redirect_url = "http://localhost/simple-oidc-client-php/refreshtoken.php";
// add scopes as keys and a friendly message of the scope as value
$scopesDefine = array(
'openid' => 'log in using your identity',
'email' => 'read your email address',
'profile' => 'read your basic profile info',
);
// refreshtoken.php interface configuration
$refresh_token_note = "NOTE: New refresh tokens expire in 12 months.";
$access_token_note = "NOTE: New access tokens expire in 1 hour.";
$manage_token_note = "You can manage your refresh tokens in the following link: ";
$manageTokens = $issuer . "manage/user/services";
$sessionName = "simple-oidc-client-php";
$sessionLifetime = 60*60; // must be equal to access token validation time in seconds
The migration guide below applies to OIDC clients registered in the Development and the Demo environment of Check-in. Beginning June 24, 2022, clients using the legacy Check-in OIDC endpoints will no longer be supported
All the clients that were registered in MITREid Connect have been moved to Keycloak preserving all the options (Client ID, Client Secret, Redirect URIs etc.), so you do not need to re-register your Service.
The first thing you need to do is to update the OIDC endpoints according to the
Endpoints table. If the Application/Library supports Dynamic
Discovery, then you need to update on the issuer
. Otherwise, you need to
update all the Endpoints separately.
The size of the Access/Refresh Tokens that are issued by Keycloak is larger of the respective Tokens created by MITREid Connect. For example, the size of an Access Token is around 1400 characters, depending on the information that are included in the payload of the JWT. So make sure that your OIDC implementation can handle larger Tokens.
The Redirect URI query parameter in the logout request has been changed from
redirect
to post_logout_redirect_uri
and must be URL encoded. Also, the
value of the post_logout_redirect_uri
must be defined in the Valid Redirect
URIs of the Service configuration in the EGI Federation Registry.
The Token Introspection is available to all the clients that are using any
authentication method (client_secret_basic
, client_secret_post
,
client_secret_jwt
or private_key_jwt
) (Confidential Clients) to the Token
Endpoint. Public Clients (clients that do not use any authentication method)
will not be able to get a successful response from the Introspection Endpoint.
Saying that, the “Introspection” option in the EGI Federation Registry will be
removed.
If you are not using PKCE (Proof Key for Code Exchange), please make sure to disable the “PKCE Code Challenge Method” in the Service configuration in EGI Federation Registry, otherwise you will get the following HTTP response during the authentication flow:
error=invalid_request&error_description=Missing parameter: code_challenge_method
If you are using the Token Exchange grant, please make sure that the audience
(Optional) defines the logical name of the service that the token will be used
for; when specified, it must match the client ID of a client registered in
Check-in otherwise an invalid_client
error is returned
("description": "audience not found"
)
If you are using the Client Credentials grant, there is a minor change in the
responses from userinfo and introspection endpoints. The Client ID of the
client is not released as the sub
claim any more and has replaced with by
the client_id
claim. The sub
contains the identifier of the client which is
unique, non-reassignable and scoped @egi.eu
.
If you have obtained an Refresh Token from EGI Check-in Token Portal or oidc-agent issued by the MITREid Connect instance, you will need to replace them by creating new Refresh Tokens issued by Keycloak.
If you have obtained Refresh Tokens using the EGI Check-in Token Portal, please check the following table:
Issuer | Demo environment | Development environment |
---|---|---|
Keycloak | https://aai-demo.egi.eu/token | https://aai-dev.egi.eu/token |
MITREid Connect (Legacy) | https://aai-demo.egi.eu/token-legacy | https://aai-dev.egi.eu/token-legacy |
If you have obtained Refresh Tokens using the oidc-agent, please use the following command:
oidc-gen --pub --issuer <ISSUER> --scope ...
code_challenge
, code_challenge_method
or code_verifier
HTTP parameterIf you get error messages containing the PKCE HTTP parameters, probably the PKCE mode is enabled in your Service Configuration but the Application is not performing the PKCE mode.
To solve this, you need to follow the steps below:
invalid_code
If you try to perform the Authorization Code flow and you get an invalid_code
error message, probably the Application sends the authorization request to the
Authorization Endpoint of the Keycloak based EGI Check-in OP and then sends the
code
to the Token Endpoint of the MITREid Connect based EGI Check-in OP or
vice versa.
To fix this you need to verify that you have updated all the OIDC Endpoints with the Keycloak ones. You can find all the OIDC Endpoints of Keycloak in the Endpoint table.
redirect_uri
If you try to perform the Authorization Code flow and you get an
invalid_redirect_uri
error, probably the redirect_uri
in the Authorization
Request mismatches with the Allowed Redirect URIs in the Service Configuration.
To solve this, you need to follow the steps below:
invalid_token
or 401 Unauthorized
error responseIf you are trying to make a request to the UserInfo Endpoint and the response
contains the invalid_token
error message, probably you are using an invalid
Token or the UserInfo endpoint is wrong.
To solve this, please make sure the that:
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. EGI is running two Master Portal instances, one development, one production instance.
Endpoint | Production environment |
---|---|
Provider configuration | https://aai.egi.eu/mp-oa2-server/.well-known/openid-configuration |
Client registration | https://aai.egi.eu/mp-oa2-server/register |
Authorisation | https://aai.egi.eu/mp-oa2-server/authorize |
Token | https://aai.egi.eu/mp-oa2-server/token |
JSON Web Key(jwt) | https://aai.egi.eu/mp-oa2-server/certs |
User Info | https://aai.egi.eu/mp-oa2-server/userinfo |
Endpoint | Development environment |
---|---|
Provider configuration | https://masterportal-pilot.aai.egi.eu/mp-oa2-server/.well-known/openid-configuration |
Client registration | https://masterportal-pilot.aai.egi.eu/mp-oa2-server/register |
Authorisation | https://masterportal-pilot.aai.egi.eu/mp-oa2-server/authorize |
Token | https://masterportal-pilot.aai.egi.eu/mp-oa2-server/token |
JSON Web Key(jwt) | https://masterportal-pilot.aai.egi.eu/mp-oa2-server/certs |
User Info | https://masterportal-pilot.aai.egi.eu/mp-oa2-server/userinfo |
In order to register a new client for your VO portal go to:
client_id
and
client_secret
in a secure placeIn order to get the client approved, send an email to the administrator of the
EGI Master Portal using checkin-support
<AT>
mailman.egi.eu
.
For further and detailed instructions on the integration flow, see the generic RCAuth.eu MasterPortal VOPortal integration guide
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.
This section defines the attributes that can be made available to services connected to Check-in.
attribute name | Community User Identifier |
---|---|
description | The User’s Community Identifier is a globally unique, opaque, persistent and non-reassignable identifier identifying the user. For users whose community identity is managed by Check-in, this identifier is of the form <uniqueID>@egi.eu . The <uniqueID> portion is an opaque identifier issued by Check-in |
SAML Attribute(s) |
|
OIDC scope |
|
OIDC claim(s) |
|
OIDC claim location |
|
origin | The Community User Identifier is assigned by Check-in or an external AAI service managing the community identity of the user |
changes | No |
multiplicity | No |
availability | Always |
example | ef72285491ffe53c39b75bdcef46689f5d26ddfa00312365cc4fb5ce97e9ca87@egi.eu |
notes | Use Community User Identifier within your application as the unique-identifier key for the user. Obtaining the Community User Identifier from the sub claim using the openid scope for OIDC Relying Parties or from eduPersonUniqueId for SAML Relying Parties will be deprecated. OIDC RPs should request either the voperson_id or aarc scope to obtain the Community User Identifier. SAML PRs should request the voPersonID attribute to obtain the Community User Identifier. |
status | Stable |
attribute name | Display Name |
---|---|
description | The user’s full name, in a displayable form |
SAML Attribute(s) | urn:oid:2.16.840.1.113730.3.1.241 (displayName) |
OIDC scope |
|
OIDC claim(s) | name |
OIDC claim location | Userinfo endpoint |
origin | Provided by user’s Identity Provider |
changes | Yes |
multiplicity | Single-valued |
availability | Always |
example | John Doe |
notes | - |
status | Stable |
attribute name | Given Name |
---|---|
description | The user’s first name |
SAML Attribute(s) | urn:oid:2.5.4.42 (givenName) |
OIDC scope |
|
OIDC claim(s) | given_name |
OIDC claim location | Userinfo endpoint |
origin | Provided by user’s Identity Provider |
changes | Yes |
multiplicity | Single-valued |
availability | Always |
example | John |
notes | - |
status | Stable |
attribute name | Family Name |
---|---|
description | The user’s last name |
SAML Attribute(s) | urn:oid:2.5.4.4 (sn) |
OIDC scope |
|
OIDC claim(s) | family_name |
OIDC claim location | Userinfo endpoint |
origin | Provided by user’s Identity Provider |
changes | Yes |
multiplicity | Single-valued |
availability | Always |
example | Doe |
notes | - |
status | Stable |
attribute name | Username |
---|---|
description | The username by which the user wishes to be referred to |
SAML Attribute(s) | urn:oid:0.9.2342.19200300.100.1.1 (uid) |
OIDC scope |
|
OIDC claim(s) | preferred_username |
OIDC claim location |
|
origin | Check-in assigns this attribute on user registration |
changes | No |
multiplicity | Single-valued |
availability | Always |
example | jdoe |
notes | The Service Provider MUST NOT rely upon this value being unique |
status | Stable |
attribute name | Email Address |
---|---|
description | The user’s email address |
SAML Attribute(s) | urn:oid:0.9.2342.19200300.100.1.3 (mail) |
OIDC scope |
|
OIDC claim(s) | email |
OIDC claim location |
|
origin | Provided by user’s Identity Provider |
changes | Yes |
multiplicity | Single-valued |
availability | Always |
example | john.doe@example.org |
notes | This MAY NOT be unique and is NOT suitable for use as a primary key |
status | Stable |
attribute name | Verified email flag |
---|---|
description | True if the user’s email address has been verified; otherwise false |
SAML Attribute(s) | See Verified email list |
OIDC scope |
|
OIDC claim(s) | email_verified |
OIDC claim location |
|
origin | Check-in assigns this attribute on user registration |
changes | Yes |
multiplicity | Single-valued |
availability | Always |
example | true |
notes | This claim is available only in OpenID Connect |
status | Stable |
attribute name | Verified email list |
---|---|
description | A list of user’s email addresses that have been verified |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.25178.4.1.14 (voPersonVerifiedEmail) |
OIDC scope |
|
OIDC claim(s) | voperson_verified_email |
OIDC claim location |
|
origin | Check-in or the user’s Identity Provider |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example |
|
notes | - |
status | Experimental |
attribute name | Affiliation |
---|---|
description | The user’s affiliation within a particular security domain (scope) |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.5923.1.1.1.9 (eduPersonScopedAffiliation) |
OIDC scope | eduperson_scoped_affiliation |
OIDC claim(s) | eduperson_scoped_affiliation |
OIDC claim location |
|
origin | Check-in assigns this attribute on user registration |
changes | Yes |
multiplicity | Multi-valued |
availability | Always |
example |
|
notes | Service Providers are encouraged to validate the scope of this attribute |
status | Stable |
attribute name | Groups |
---|---|
description | The user’s group/VO membership/role information expressed as entitlements |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.5923.1.1.1.7 (eduPersonEntitlement) |
OIDC scope | eduperson_entitlement |
OIDC claim(s) | eduperson_entitlement |
OIDC claim location |
|
origin | Group memberships are managed by group administrators |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example |
|
notes | - |
status | Stable |
attribute name | Capabilities |
---|---|
description | This attribute describes the resource or child-resource a user is allowed to access, optionally specifying certain actions the user is entitled to perform, as described in AARC-G027 |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.5923.1.1.1.7 (eduPersonEntitlement) |
OIDC scope | eduperson_entitlement |
OIDC claim(s) | eduperson_entitlement |
OIDC claim location |
|
origin | Capabilities are managed by Check-in |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example |
|
notes | - |
status | Stable |
attribute name | GOCDB Roles |
---|---|
description | The user’s GOCDB role information expressed as entitlements |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.5923.1.1.1.7 (eduPersonEntitlement) |
OIDC scope | eduperson_entitlement |
OIDC claim(s) | eduperson_entitlement |
OIDC claim location |
|
origin | The roles are managed in GOCDB |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example |
|
notes | - |
status | Stable |
attribute name | Assurance |
---|---|
description | Assurance of the identity of the user, following REFEDS Assurance Framework (RAF) and the EGI AAI Assurance Profiles. The following RAF values are qualified and automatically set for all Community identities:
|
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.5923.1.1.1.11 (eduPersonAssurance) |
OIDC scope | eduperson_assurance |
OIDC claim(s) | eduperson_assurance |
OIDC claim location |
|
origin | Check-in assigns this attribute on user registration |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example |
|
notes | - |
status | Stable |
attribute name | CertEntitlement |
---|---|
description | Provides information about the user’s certificate subject(s) and the associated VO(s) |
SAML Attribute(s) | Not available |
OIDC scope | cert_entitlement |
OIDC claim(s) | cert_entitlement |
OIDC claim location |
|
origin | VO/group management tools integrated with Check-in |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example | [{"cert_subject_dn": "/C=GR/O=HellasGrid/...","cert_iss": "/C=GR/O=HellasGrid/...","eduperson_entitlement": "urn:mace:egi.eu:group:checkin-integration:role=VO-Admin#aai.egi.eu"}] |
notes | This is available only for DIRAC |
status | Stable |
attribute name | SSH Public Key |
---|---|
description | Provides information about the user’s SSH public key(s) |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.24552.500.1.1.1.13 (sshPublicKey) |
OIDC scope | ssh_public_key |
OIDC claim(s) | ssh_public_key |
OIDC claim location | Userinfo endpoint |
origin | Added SSH public key(s) in user’s Check-in Profile |
changes | Yes |
multiplicity | Multi-valued |
availability | Not always |
example |
|
notes | - |
status | Experimental |
attribute name | ORCID iD |
---|---|
description | Provides information about the user’s ORCID iD |
SAML Attribute(s) | urn:oid:1.3.6.1.4.1.5923.1.1.1.16 (eduPersonOrcid) |
OIDC scope | orcid |
OIDC claim(s) | orcid |
OIDC claim location | Userinfo endpoint |
origin | ORCID Identity Provider |
changes | No |
multiplicity | Single-valued |
availability | Not always |
example | https://orcid.org/XXXX-XXXX-XXXX-XXXX |
notes | The attribute is available when logging in using ORCID |
status | Experimental |
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 is encoded in entitlements
(eduPersonEntitlement
attribute values in SAML or eduperson_entitlement
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.
An entitlement value expressing group membership and role information has the following syntax (components enclosed in square brackets are OPTIONAL):
urn:mace:egi.eu:group:<GROUP>[:<SUBGROUP>*][:role=<ROLE>]#<GROUP-AUTHORITY>
where:
<GROUP>
is the name of a VO, research collaboration or a top level arbitrary
group. <GROUP>
names are unique within the urn:mace:egi.eu:group
namespace;<SUBGROUP>
components represent the hierarchy of subgroups in
the <GROUP>
; specifying sub-groups is optional<ROLE>
component is scoped to the rightmost (sub)group; if no
group information is specified, the role applies to the VO<GROUP-AUTHORITY>
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
informationExample:
urn:mace:egi.eu:group:fedcloud.egi.eu:role=vm_operator#aai.egi.eu
The user’s capability information is encoded in entitlements
(eduPersonEntitlement
attribute values in SAML or eduperson_entitlement
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 following the syntax defined in
AARC-G027.
An entitlement value expressing a capability has the following syntax (components enclosed in square brackets are OPTIONAL):
<NAMESPACE>:res:<RESOURCE>[:<CHILD-RESOURCE>]...[:act:<ACTION>[,<ACTION>]...]#<AUTHORITY>
where:
<NAMESPACE>
is controlled by the e-infrastructure, research infrastructure
or research collaboration that manages the capability. The <NAMESPACE>
of
capabilities managed by Check-in is set to urn:mace:egi.eu
, while,
generally, it is in the form of
urn:<NID>:<DELEGATED-NAMESPACE>[:<SUBNAMESPACE>]...
where:
<NID>
is the namespace identifier associated with a URN namespace
registered with IANA2, ensuring global uniqueness. Implementers SHOULD use
one of the existing registered URN namespaces, such as
urn:mace
[MACE].
<DELEGATED-NAMESPACE>
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. It is RECOMMENDED that a
publicly accessible URN value registry for each delegated namespace be
provided.
The literal string "res"
indicates that this is a resource-specific
entitlement as opposed to, for example, an entitlement used for expressing
group membership
AARC-G002.
<RESOURCE>
is the name of the resource. Whether the name should be unique is
an implementation decision.
An optional list of colon-separated <CHILD-RESOURCE>
components represents a
specific branch of the hierarchy of resources under the identified
<RESOURCE>
.
An optional list of comma-separated <ACTION>
s MAY be included, which, if
present, MUST be prefixed with the literal string “act”. This component MAY be
used for further specifying the actions a user is entitled to do at a given
resource. Note that the list of <ACTION>
s is scoped to the rightmost
child-resource; if no child-resource information is specified, actions apply
to the top level resource. The interpretation of a capability without actions
specified is an implementation detail.
<AUTHORITY>
is a mandatory and non-empty string that indicates the
authoritative source of the capability. This SHOULD be used to further specify
the exact issuing instance. For example, it MAY be the FQDN of the service
that issued that specific capability. The <AUTHORITY>
is specified in the
f-component RFC8141 of the URN; thus,
it is introduced by the number sign ("#") character and terminated by the end
of the URN. All characters must be encoded according to
RFC8141. Hence, the <AUTHORITY>
MUST
NOT be considered when determining equivalence (Section 3 in
RFC8141) of URN-formatted capabilities.
The <AUTHORITY>
of capabilities managed by Check-in is typically set to
aai.egi.eu
.
Example:
urn:mace:egi.eu:res:rcauth#aai.egi.eu
Based on the authentication method selected by the user, the EGI proxy assigns a
Identity Assurance, which is conveyed to the SP through both the
eduPersonAssurance
attribute and the Authentication Context Class
(AuthnContextClassRef
) of the SAML authentication response. EGI Check-in uses
Assurance Profiles which distinguish between three Identity Assurance levels,
similarly to the
eID Assurance Framework (eIDAF).
Each level is represented by a URI as follows:
https://aai.egi.eu/LoA#Low
https://aai.egi.eu/LoA#Substantial
https://aai.egi.eu/LoA#High
Moreover, EGI Check-in follows the
REFEDS Assurance framework (RAF).
The EGI Check-in conveys any RAF values provided by the IdP directly to the SP,
through the aforementioned methods. Furthermore, Check-in will append into the
User’s profile any additional LoA, if the user is eligible for it. For example,
a user having a Verified Email is eligible for the RAF value
https://refeds.org/assurance/IAP/low
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:
GOCDB roles, as per
GOCDB documentations, are
encoded (eduPersonEntitlement
attribute values in SAML or
eduperson_entitlement
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.
An entitlement value expressing GOCDB roles has the following syntax (components enclosed in square brackets are OPTIONAL):
urn:mace:egi.eu:goc.egi.eu:<PRIMARY_KEY>:<ON_ENTITY>:<USER_ROLE>@egi.eu
where:
<PRIMARY_KEY>
is the primary key for the user role, e.g. “123G0”<ON_ENTITY>
is the name of the entity on which the user role applies to,
e.g. “GRIDOPS-GOCDB”<USER_ROLE>
is the user’s role, e.g. “Site Operations Manager”Example:
urn:mace:egi.eu:goc.egi.eu:100453G0:GRIDOPS-CheckIn:Site+Administrator@egi.eu