What does "offline" access in OAuth mean?

By design the access tokens returned by the OAuth flow expire after a period of time (1 hour for Google access tokens), as a safety mechanism. This means that any application that wants to work with a user's data needs the user to have recently gone through the OAuth flow, aka be online. Requesting offline access provides the application a refresh token it can use to generate new access tokens, allowing it to access user data long after the data has gone through the OAuth flow, aka when they are offline.

Getting offline access is needed when your application continues to run when the user isn't present. For instance, if there is some nightly batch process, or if your application responds to external events like push notifications. However if you only access user data while the user is actively using your application then there is no need for offline access. Just send the user through the OAuth flow every time you need n access token, and if they've previously granted access to your application the authorization page will instantly close, making the process nearly invisible to the user.

For Google APIs, you can request offline access by including the parameter access_type=offline in the authorization URL you present to your users. Offline access, and hence refresh tokens, is requested automatically when using the Installed Application flow.


Offline access is IMO a really bad name for it, and I think its a term only Google uses its not in the RFC for OAuth as far as I remember.

What is Google offline access?

When you request offline access the Google Authentication server returns a refresh token. Refresh tokens give your application the ability to request data on behalf of the user when the user is not present and in front of your application.

Example of an app needing offline access

Let's say I have a Super Awesome app that downloads your Google Analytics Data, makes it into a nice PDF file and emails it to you every morning with your stats. For this to work my application needs to have the ability to access your Google Analytics data when you are not around, to give me permission to do that. So Super Awesome app would request offline access and the authentication server would return a refresh token. With that refresh token Super awesome app can request a new access token whenever it wants and get your Google Analytics data.

Example of an app not needing offline access

Let's try Less Awesome app that lets you upload files to Google Drive. Less Awesome app doesn't need to access your Google drive account when you're not around. It only needs to access it when you are online. So in theory it wouldn't need offline access. But in practice it does, it still gets a refresh token so that it won't have to ask you for permission again (this is where I think the naming is incorrect).

Helpful quote from the OpenStack documentation:

If a refresh token is present in the authorization code exchange, then it can be used to obtain new access tokens at any time. This is called offline access, because the user does not have to be present at the browser when the application obtains a new access token.


The truth about offline access

The thing is that in a lot of cases the authentication server will return the refresh token to you no matter what: You don't have to actually ask for anything – it gives it to you. Giving you the ability to access the users data when they aren't around. Users don't know that you could access their data without them being there. It's only the JavaScript library and I think the PHP library that hide the refresh token from you, but it's there.

Example

By just posting (i.e. HTTP POST request):

https://accounts.google.com/o/oauth2/token?code={AuthCode}&
client_id={ClientId}.apps.googleusercontent.com&client_secret={ClientSecret}&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&grant_type=authorization_code

Here is the response:

{
   "access_token": "ya29.1.AADtN_VSBMC2Ga2lhxsTKjVQ_ROco8VbD6h01aj4PcKHLm6qvHbNtn-_BIzXMw",
   "token_type":   "Bearer",
   "expires_in":   3600,
   "refresh_token": "1/J-3zPA8XR1o_cXebV9sDKn_f5MTqaFhKFxH-3PUPiJ4"
}

I now have offline access to this users data, and I never told them that I would have it. More details be found in this short article: Google 3 legged OAuth2 flow.


Useful reading

  • Using OAuth 2.0 for Web Server Applications
  • Understanding Refresh Tokens