SURF research access management offers basic support for token-based applications.

A user can create a token to use with a specific application in the SURF research access management user interface. When the user accesses the applications (for example, via an API), the application presents the token to SURF research access management via the introspection endpoint, and SURF research access management will tell the application if the token is valid, and if so, to which user it was issued.

Configuring the application

With the application admin role, enable 'User token introspection'. The introspection endpoint for use by the application is listed.

Next, create a token for use by the application by the 'New token' button. This token authorizes the application to call the introspection endpoint. This is not the token for the user.

The token will only be displayed this once.

Creating a user token

A token-based applications needs to be connected to a collaboration like any other application. Once the user has access to the applications via one of their collaborations, a 'Application tokens' tab appears on the collaboration screen.The tab lists the user's current tokens, and allows creating new ones.

The tab is called an 'application token', because from the point of view of a regular member of a collaboration, it is used to gain (API) access to an application. (From the perspective of an application admins, there are multiple other types of 'application tokens'.)

The token will only be displayed this once. The token expires after a fixed number of days (to be specified by the application); after that time, the user will have to manually renew it.

After having generated a token, the user can use it to gain access to the application. How the application implements this it up to the application admin, but we recommend only using it for programmatic API access only. Authentication users for a user interface, either web-based or a CLI, is much better handled via SAML or OpenID Connect.

Validating a user token

When a user authenticates at an application using a token, the application can verify the token at SURF research access management by posting the token as a application/x-www-form-urlencoded document to the introspection endpoint as listed at the application settings tab.

POST /api/tokens/introspect HTTP/2
Host: sram.surf.nl
authorization: bearer ABCxxxxxxxxxxxxx-yyyyyyyyyyyyyyyyXYZ
content-length: 50
content-type: application/x-www-form-urlencoded

token=AnXQYCsu7VSO33OgqEX_tOzhxsRkGby2K3pIqeoaav_U

If the token is valid, SURF research access management will reply with information about the use who has generated the token:

HTTP/2 200
content-type: application/json

{
  "active": true,
  "aud": "token_example",
  "client_id": "token_example",
  "exp": 1643039909,
  "iat": 1643039609,
  "iss": "https://acc.sram.surf.nl",
  "status": "token-valid",
  "sub": "6ce7f9e8bc9b760174d147016e4d039ead4b4b3a@acc.sram.eduteams.org",
  "user": {
    "eduperson_entitlement ": [
      "urn:mace:surf.nl:sram-acc:group:uniharderwijk",
      "urn:mace:surf.nl:sram-acc:group:uniharderwijk:example_co"
    ],
    "email": "bas+pietvoorbeeld@zoetekouw.net",
    "familiy_name": "Voorbeeld",
    "given_name": "Piet",
    "name": "Piet Voorbeeld",
    "sub": "6ce7f9e8bc9b760174d147016e4d039ead4b4b3a@acc.sram.eduteams.org",
    "uid": "6ce7f9e8bc9b760174d147016e4d039ead4b4b3a@acc.sram.eduteams.org",
    "username": "pvoorbeeld",
    "voperson_external_affiliation": "affiliate@eduid.nl",
    "voperson_external_id": "f12ef859-c4f3-424c-80f5-2606d34371b6@eduid.nl"
  },
  "username": "pvoorbeeld"
}

If the token is not valid, SURF research access management will return an error:

HTTP/2 200
content-type: application/json

{
  "active": false,
  "status": "token-unknown"
}

Other possible error messages that can be returned are: