You can use the SURFconext OpenID Connect access_tokens to protect your API as well. In the OAuth2 introspection spec, the API consuming access_tokens is referred to as a "resource server". The aforementioned specification standardizes the the way the access_token verification takes place. Many client libraries support introspection.

If you want to see a live demo, please refer to our OpenID Connect playground application

More information on how to connect your Resource server using the SP Dashboard can be found here

The flow works as follows

1) A regular relying party that is connected to SURFconext triggers a login request. The user will log in, and the relying party gets an access_token and id_token, simplified:

  "access_token": "ABC123",
  "token_type": "Bearer",
  "id_token": "DEF456"

2) The Relying Party can now use the access_token to make an authenticated request to the API on behalf of the user

Such a request looks like this:

GET https://url.of.the.api/api/student/grades
"Authorization": "Bearer ABC123",
"Accept": "application/json, application/json;charset=UTF-8"

3) The API receives that request, and verifies the access_token with the SURFconext OIDC server. This verification process is called "introspection". The API uses a username and password to identify itself, using basic authentication. The token is in the body of the POST.

"Authorization": "aW50cm9zcGVjdDpzZWNyZXQK",
"Accept": "application/json, application/json;charset=UTF-8"
token: ABC123

4) The introspect endpoint will answer with a JSON document with information on the access_token and additional claims of the user.

  "active": true
  "authenticating_authority": "", 
  "client_id": "playground_client", 
  "email": "", 
  "exp": 1574703028, 
  "family_name": "Testuser", 
  "given_name": "Test",
  "iss": "", 
  "schac_home_organization": "",
  "scope": "openid", 
  "sub": "01cafaaa7bc2dd124f45487fbcc740ec3ea6f54", 
  "token_type": "Bearer", 
  "updated_at": 1574695827 

The SURFconext OpenID connect endpoint supports properties with information of the access_token, and gives back claims

activeBoolean, indicates the validity of the access_token
SchacHomeOrganization of the IdP that authenticated the user
client_idThe client_id of the Client that requested the access_token
expUnix timestamp indicating the expiration date of the access_token
issThe issuer of the access_token
scopeList of scopes of this access_token
subThe subject of the user. Matches the subject of the id_token
token_typeToken type
updated_atLast time the token was updated, is in our case always the unix timestamp when the token was issued

The rest of the token consists of claims. See this page for more information on the OpenID Connect claims supplied by SURFconext.

  • No labels