Advanced service authentication and registration

For the Advanced Authentication method your service does not send a client secret but it uses a self signed client assertion to obtain the access token for the OpenAIRE APIs. The client assertion is a JWT that must be signed with RSASSA using SHA-256 hash algorithm. The OpenAIRE AAI server validates the client assertion using the public key that you have provided upon the service registration.

Prepare to register your service

Before you register your service you need to prepare a pair of a private key and a public key on your side.

To create the key pair you have the following options:

• Use OpenAIRE authorization server built in tool. You can access the service here: https://aai.openaire.eu/oidc/generate-oidc-keystore.
  The response is your Public and Private Keypair and has the following format:

  { "p" : ...,
     "kty" : "RSA",
     "q" : ...,
     "d" : ...,
     "e" : "AQAB",
     "kid" : ...,
     "qi" : ..., 
     "dp" : ..., 
     "alg" : "RS256",
     "dq" : ...,
     "n" : ....
  }

  Use the public key parameters (kty, e, kid, alg, n) to create your Public Key in the following format:

  {
     "kty": "RSA",
     "e": "AQAB",
     "kid": ...,
     "alg": "RS256",
     "n": ...
  }

  Store both the Public and Private keypair and the Public key. You will need them to register your service.
  Store the Public and Private keypair confidentially on the service side.
• Use openssl and then convert the keys to jwk format using PEM to JWK scripts, such as https://github.com/danedmunds/pem-to-jwk. Alternatively, the client application can read the key pair in PEM format and then convert them, using JWK libraries. Use the public key parameters (kty, e, kid, alg, n) to the service registration.

How to register your service

To register your service you need to:

1. Login to OpenAIRE. In case you are not already a member you will need to register first.
2. Go to your Registered Services page and click the New Service button.
3. Provide the "Νame" (mandatory) of your service.
4. Select the Advanced "Security level"
5. Use the public key parameters (kty, e, kid, alg, n) you previously produced to declare your "Public Key" "By value" in the following format:

   {
      "kty": "RSA",
      "e": "AQAB",
      "kid": ...,
      "alg": "RS256",
      "n": ...
   }

   - OR -

   If your service has a public key in JWK format that can be accessed using a link, you can set “Public Key” to “By URL”.

6. Click the Add New Service button.

Once your service is created it will appear in the list of your Registered Services page, with the Service Id that was automatically assigned to it by the AAI OpenAIRE service.

How to make a request

Step 1. Create and sign a JWT

Your service must create and sign a JWT and include it in the request to token endpoint as described in the OpenID Connect Core 1.0, 9. Client Authentication.

To create a JWT you can use https://mkjose.org/. To do so you need to create a payload that should contain the following claims:

{
   "iss": "{SERVICE_ID}",
   "sub": "{SERVICE_ID}",
   "aud": "https://aai.openaire.eu/oidc/token",
   "jti": "{RANDOM_STRING}",
   "exp": {EXPIRATION_TIME_OF_SIGNED_JWT}
}

• iss, (required) the “issuer” claim identifies the principal that issued the JWT. The value is the Service Id that was created when you registered your service.
• sub, (required) the “subject” claim identifies the principal that is the subject of the JWT. The value is the Service Id that was created when you registered your service.
• aud, (required) the “audience” claim identifies the recipients that the JWT is intended for. The value is https://aai.openaire.eu/oidc/token>.
• jti, (required) The “JWT ID” claim provides a unique identifier for the JWT. The value is a random string.
• exp, (required) the “expiration time” claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The value is a timestamp in epoch format.

Fill in the payload in the form available at https://mkjose.org/, select the Signing Algorithm to be RS256 using SHA-256 and paste the Public and Private Keypair previously created.

To check your JWT you can go to https://jwt.io/. The header should contain the following claims:

{
   "alg": "RS256",
   "kid": ...
   }

where kid is the one of your Public and Private Keypair you used to sign the JWT in Step 1.

Step 2. Request for an access token

To make an access token request use the signed JWT that you created in Step 1. The OpenAIRE AAI server will check if the signed JWT is valid using the public key that you declared in the "How to register your service" process.

   curl -k -X POST "https://aai.openaire.eu/oidc/token" \
   -d "grant_type=client_credentials" \
   -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
   -d "client_assertion={signedJWT}"

where {signedJWT} is the signed JWT created in Step 1.

The response is:

{
   "access_token": {ACCESS_TOKEN}
   "token_type":"Bearer",
   "expires_in": ...,
   "scope":"openid"
}

Step 3. Make a request

To access the OpenAIRE APIs send the access token returned in Step 2.

   GET https://test.openaire.eu/{resourceServicePath}
   Authorization: Bearer {ACCESS_TOKEN}

Error messages

401 - Invalid client assertion

{
   "error":"invalid_client",
   "error_description":"Bad client credentials"
}

401 - Client assertion for missing service

{
   "error":"invalid_client",
   "error_description":"Could not find client {SERVICE_ID}"
}

401 - Expired signed jwt

{
   "error":"unauthorized",
   "error_description":"Assertion Token in expired: {EXPIRATION_TIME}"
}