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 headers: "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.
POST https://connect.surfconext.nl/oidc/introspect
headers:
"Authorization": "aW50cm9zcGVjdDpzZWNyZXQK",
"Accept": "application/json, application/json;charset=UTF-8"
"Body":
{
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": "https://idp.instition.nl",
"client_id": "playground_client",
"email": "testuser@universityofharderwijk.nl",
"exp": 1574703028,
"family_name": "Testuser",
"given_name": "Test",
"iss": "https://connect.surfconext.nl",
"schac_home_organization": "universityofharderwijk.nl",
"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
| Property | Explanation |
|---|---|
| active | Boolean, indicates the validity of the access_token |
authenticating_authority | SchacHomeOrganization of the IdP that authenticated the user |
| client_id | The client_id of the Client that requested the access_token |
| exp | Unix timestamp indicating the expiration date of the access_token |
| iss | The issuer of the access_token |
| scope | List of scopes of this access_token |
| sub | The subject of the user. Matches the subject of the id_token |
| token_type | Token type |
| updated_at | Last 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.