You can use the SURFconext OpenID Connect access_tokens to protect your API as well. In the OAuth2 introspection spec, this 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:
...
Such a request looks like this:
| Code Block | ||
|---|---|---|
| ||
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.
| Code Block | ||
|---|---|---|
| ||
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 an answer a JSON document with information on the validity of the access_token , and returns the subject and the additional claims of the user, so the API knows for which user the access_token has been issued:.
| Code Block | ||
|---|---|---|
| ||
{
"active": true, (boolean whether the access_token is valid)
"authenticating_authority": "https://idp.instition.nl", (the IdP that authenticated the user)
"client_id": "playground_client", (the client_id of the RP to which the access_token was issued)
"email": "testuser@universityofharderwijk.nl", (email address of the user)
"exp": 1574703028, (expiration date of the access_token)
"family_name": "Testuser", (surname)
"given_name": "Test", (name)
"iss": "https://connect.surfconext.nl", (issuer of the token)
"schac_home_organization": "universityofharderwijk.nl", (Schac Home organisation claim)
"scope": "openid", (scope)
"sub": "01cafaaa7bc2dd124f45487fbcc740ec3ea6f54", (Subject, the RP knows the subject as well, from the id_token)
"token_type": "Bearer", (token type)
"updated_at": 1574695827 (date when this token was updated
} |
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.