FUNDify

Authentication process of external API clients

A key functionality of FUNDify is to provide an API that can be used by external API clients (e.g. the Technical University of Vienna) to retrieve information about annotated calls. This information is then displayed in their internal tools, e.g. in a wiki page.
This page describes the process how the clients can authenticate against FUNDify API.
Standard oAuth client credentials flow is used. Refer to this excellent documentation about it by Auth0: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow

Requesting access

Interested parties should fill in the contact form and indicate they wish to consume FUNDify API.

Creating the accounts

• The accounts are are created by the TU Keycloak team:
• Request the creation of an API client, and they should send you
o Client ID
o Client Secret
o Service Account User ID

Setting permissions for the service account

• After the account has been created, proper permissions need to be set in FUNDify
• This means granting the service account the role “EXTERNAL_API_CLIENT” and setting the correct affiliation ID
• These properties are managed via the FUNDify application

Sending credentials to the requesting party

The API consumers will need to following:
• Client ID (similar to an username)
• Client Secret (similar to a password)
• Token endpoint (similar to a login site)
The client ID and client secret are highly sensitive information and should be submitted via a secure channel, e.g. sharing functionality of a password manager. (see e.g. https://support.1password.com/share-items )
Anyone who has the client ID and client secret can act on behalf of the service account.

Authentication of third party apis

To authenticate, clients need to:

  1. Obtain a bearer token from the token endpoint
  2. Send this token on all requests they make to our API
    The token endpoint is the following:
    https://id.arisnet.ac.at/realms/fundify/protocol/openid-connect/token

Code sample (cURL)

This simple request can be used to get an access token.
curl -X POST \
-H ‚Content-Type: application/x-www-form-urlencoded‘ \
-d ‚grant_type=client_credentials‘ \
-d ‚client_id=YOUR_CLIENT_ID‘ \
-d ‚client_secret=YOUR_CLIENT_SECRET‘
To use it, send it in the Authorization header with “Bearer ”:
curl -H „Authorization: Bearer „
Putting it together, you can do something like this:

Getting the access token and storing it in a variable

ACCESS_TOKEN=$(curl -X POST \
-H ‚Content-Type: application/x-www-form-urlencoded‘ \
-d ‚grant_type=client_credentials‘ \
-d ‚client_id=YOUR_CLIENT_ID‘ \
-d ‚client_secret=YOUR_CLIENT_SECRET‘ | jq -r ‚.access_token‘)

Sending the token on request to the FUNDify API

curl -H „Authorization: Bearer $ACCESS_TOKEN“