SURFconext supports refresh tokens. This page tries to explain what refresh tokens are, and in what context they should be used.

What are refresh tokens?

OAuth 2.0 and OpenID Connect use access tokens to access protected resources at a resource server (such as the userinfo endpoint). However, for increased security, access tokens are only valid for a limited time: when an access tokens leaks, whoever has the access token can potentially get unwanted access to the protected resource. So a shorter the lifetime of an access token lowers the chance of potential misuse. Typically the lifetime of an access token ranges between 1 and 24 hours. The lifetime can be set by service administrators in the SURFconext SP Dashboard.

The downside of short-lived access tokens is that every time the client needs a new access token, the user must re-authenticate. In web clients, this is not necessarily problematic: through SURFconext, users have Single Sign-On (SSO), so re-authenticating often occurs without user interaction. In non-web clients however, this often means leaving the app to open a web browser, login again, and go back to the app.

Refresh tokens can be used as a solution. After the access tokens have expired, the client can use a refresh token to request a new access token. There is no need for the user to login again. Refresh tokens typically have a much longer life time (up to 3-6 months for example). As long as the refresh token remains valid, it can be used to obtain a new access token without user interaction.

In what situations do I need a refresh token?

Refresh tokens are used in situations where a re-authentication significantly reduces the User Experience, for example in mobile apps where a re-authentication means leaving the app. For applications used from within a web browser, refresh tokens provide no benefit. If you want to prevent your users from logging in every time an access token expires, you should decouple the session time of your app from the lifetime of the access token.

Refresh tokens in SURFconext - some caveats

SURFconext acts as a proxy between the service and the identity provider. SURFconext therefore has no way of ensuring whether a user to whom the access or refresh token belongs is still active at their institution. The only way to assert that the user is still present in the IdP of their institution, or to receive up to date user claims is by forcing the user to login in again.

We advise strongly to make sure that all users are forced to login at least every 90 days. The SURFconext team can manually revoke refresh tokens, please contact us if need be.

How does it work?

Get in touch with us to enable refresh tokens for your application. Once activated, each access token request will result in the return of an access token and a refresh token. For future compatibility reasons we strongly advise to add the scope "offline_access" to the request. The refresh token can than be used to obtain a new access token. This looks as follows:


POST
TEST: https://connect.test.surfconext.nl/oidc/token
PRODUCTION: https://connect.test.surfconext.nl/oidc/token
Headers:
"Accept": "application/json, application/json;charset=UTF-8",
"Authorization": "XXX",
"Content-Type": "application/x-www-form-urlencoded"
----
Body:
{
"grant_type": "refresh_token",
"redirect_uri": "https://YOURAPP.TLD/redirect",
"refresh_token": "eyJraWQiOiJrZXlfMjAyMV8xMV8xOF8wMF8wMF8 etc etc",
"scope": "openid"
}


You will get a new refresh token and a new access token in return. If we have not explicitly set the refreshTokenValidity for you, it defaults to 3600 seconds (1 hour). This default value is mainly intended for testing purposes.

Please refer to our OpenID Connect playground if you want to go more into depth with the details and get some hands-on testing.

  • No labels