Using service accounts - how to

Please make sure you read the IAM Concepts before proceeding.

A client-id and secret are required for using a service account, these are provided upon new service account creations. You can request a new service account on the D4Science Support page (3rd Party App Registration). By letting an application use its own service account, you help ensuring that it can function without user intervention. Furthermore, you ensure that any resource accesses initiated by it can be traced back (accounted) to the same application.

D4Science adopts state-of-the-art industry standards for authentication and authorization. In particular, the implementation fully adopts OIDC (OpenID Connect) for authentication and UMA 2 (User Managed Authorization) for authorization flows. Both protocols are specializations of the generic OAuth 2.0 specification. JSON Web Token (JWT) Access token are used for both authentication and authorization.

Perform authorised calls to D4Science services

At this point you have requested and obtained a a clientid and client secret that authorises the service account of your application on one or more contexts (VRE/VLabs).

In order to perform authenticated calls to D4Science you must get a JSON Web Token (JWT) first [see (1)]. The token you get will be needed for calling any D4Science service running within a context [see (2)], you should make the following (authorization Basic) HTTP Request:

(1)

type: POST
request URL: https://accounts.d4science.org/auth/realms/d4science/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic *******'

Body as x-www-form-urlencoded with 2 attributes as follows:

key: grant_type
value: urn:ietf:params:oauth:grant-type:uma-ticket
key: audience
value: %2Fd4science.research-infrastructures.eu%2FD4OS ...

curl --location --request POST 'https://accounts.d4science.org/auth/realms/d4science/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic *******' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:uma-ticket' \
--data-urlencode 'audience=%2Fd4science.research-infrastructures.eu%2FD4OS ...'

 Please note:

• the Authorization header contains the word Basic, followed by a space and a base64-encoded(non-encrypted) string client-id:client-secret you were provided with;
• data-urlencode 'grant_type' .. is fixed;
• data-urlencode 'audience' changes depending on the context (VRE/VLab) your service account is authorised on, this identifier is given to you when you request a service account.

The returned token will look something like the following one:

{
    "upgraded": false,
    "access_token": "eyJhbGci***vw",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I...hbWUiOiJEZWZhdWx0IFJlc291cmNlIn1dfSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIn0.fBej5zFXhwOBbh-FAJU39EC-IqIFfWl-Er_SiCa9SXI",
    "token_type": "Bearer",
    "not-before-policy": 1618317421
}

Actual service calls

In order to invoke a service it will be necessary to insert the access_token component as bearer token in the Authorization header of the call to the service. For example, a call to list the items of the catalogue on a given context would look like the following HTTP Request:

(2) 

type: GET
request URL: https://api.d4science.org/catalogue/items?limit=10&offset=0
Accept: application/json
Authorization: Bearer  eyJhbGci***vw

curl --location --request GET 'https://api.d4science.org/catalogue/items?limit=10&offset=0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGci***vw'