My iOS mobile app consumes services that are implemented with the OAuth2.0 protocol. The OAuth access token comes along with a refresh token and an expires_in field. I saved the refresh token and access token expiration time in my app but don't have a good idea on when to use them.
expires_in?Here's information on OAuth 2.0 token refresh.
The OAuth 2.0 standard, RFC 6749, defines the expires_in field as the number of seconds to expiration:
expires_in: RECOMMENDED. The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
Upon receiving a valid access_token, expires_in value, refresh_token, etc., clients can process this by storing an expiration time and checking it on each request. This can be done using the following steps:
expires_in to an expire time (epoch, RFC-3339/ISO-8601 datetime, etc.)access_token has expiredAn example implementation is the Go oauth2 library which converts the expires_in value to a RFC 3339 date-time in the Token expiry property. expiry isn't defined by the OAuth 2.0 standard but is useful here.
When checking the time, be sure you are the same time, for example, using the same timezone by converting all times to epoch or UTC timezone.
In addition to receiving a new access_token, you may receive a new refresh_token with an expiration time further in the future. If you receive this, you should store the new refresh_token to extend the life of your session.
Another method of handling token refresh is to manually refresh after receiving an invalid token authorization error. This can be done with the previous approach or by itself.
If you attempt to use an expired access_token and you get an invalid token error, you should perform a token refresh (if your refresh token is still valid). Since different services can use different error codes for expired tokens, you can either keep track of the code for each service or an easy way to refresh tokens across services is to simply try a single refresh upon encountering a 4xx error.
Below are some error codes from popular services:
The Zapier service is one service that implements the refresh after authorization error retry.
If your refresh_token has also expired, you will need to go through the authorization process again.
The OAuth 2.0 spec doesn't define refresh token expiration or how to handle it, however, a number of APIs will return a refresh_token_expires_in property when the refresh token does expire. Different APIs will handle refresh token expiration differently so it's important to review the docs per API, but generally you may receive a new refresh token when you refresh your access token. Expiration should be handled in a similar way such as converting refresh_token_expires_in to a RFC 3339 date-time refresh_token_expiry value.
Some examples include LinkedIn, eBay, and RingCentral. In the LinkedIn API, when you refresh access tokens, you will receive a refresh token with a decreasing refresh_token_expires_in property targeting the original refresh token expiry time until you are required to auth again. The RingCentral API will return refresh tokens with a static time so the user does not have to auth again if token refreshes and refresh token updates are done consistently.
Would recommend Method 2 above since a 401 can happen for multiple reasons such as renewing a token signing certificate or clock differences:
I've implemented plenty of successful OAuth clients and have always used this technique - and avoided ever reading the expires_in field in my client side code
