What does "offline" access in OAuth mean?

Question

What exactly does the word "offline" mean with regard to the offline access granted by an OAuth server?

Does it mean that the resource server will return data about the user even when the user is logged out of the third-party application or when the user is logged out of the OAuth resource server such as Facebook or Google or Twitter?

Solution 1

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

Solution 2

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.

Comments

[Jaroslav Záruba]

the property/flag name kinda makes sense now when you explained it, but it is very confusing (sounds like something related to file-sync)

[Eric Koleda]

You make a number of incorrect statements. A refresh token is only returned if you include the parameter access_type=offline when forming the authorization prompt. Refresh tokens are not needed to to avoid asking the user for authorization, since if they have previously granted access the approval dialog will instantly close whenever you present it again.

[DaImTo]

Any opinion why google always returns a refresh token even if your application wont need to be able to access it at a later date? You don't have to supply access_type=offline you will get a refresh token anyway check my link I have tested it. So if I request Google Analytics access the scope tells the user I want to access there data, but it doesn't tell them I also have offline access.

[Eric Koleda]

The refresh token is only returned when access_type=offline is in the authorization URL you redirect the user to. The URL you showed is the token URL, which your application makes a request to in the background. You can test the offline and online flows in the OAuth2 playground, using the gear icon to change the access type, disable the forcing of the approval prompt, etc.

[DaImTo]

Make the calls manually yourself daimto.com/google-3-legged-oauth2-flow I think Oauth2 playground tweeks it somehow. If you talk directly to the Authentication server using a native client id you will always get a refresh Token. I haven't tested it using a web token example accounts.google.com/o/oauth2/token code=4/X9lG6uWd8-MMJPElWggHZRzyFKtp.QubAT_P-GEwePvB8fYmgkJzn‌​tDnaiAI&client_id={C‌​lientId}.apps.google‌​usercontent.com&clie‌​nt_secret={ClientSec‌​ret}&redirect_uri=ur‌​n:ietf:wg:oauth:2.0:‌​oob&grant_type=autho‌​rization_code

[Eric Koleda]

Ah, it seems that refresh_tokens are provided automatically when using the installed application flow. I've updated my answer to refresh this edge case.

[DaImTo]

Ok So why doesn't Google tell people that they are also granting your application off line access? I use Eric's awesome app grant it access to my Google drive Auth screen says grant Erics awesome app access to your drive I grant it. Eric's awesome app can now read all my files when ever it wants. Not just when I am running Awesome app

[Qasim]

@EricKoleda Is that information still current? I'm passing access_type=offline in my GET string to Google, and I still don't get asked for offline access permissions.

[DaImTo]

Try adding prompt=consent

[Kermit]

all the names are bad. Authorization Server performs authentication

[mr5]

This answer tells more truth than the one accepted.

[jmrah]

[the app] still gets a refresh token so that it wont have to ask you for permission again. @DalmTo Do you consider the quoted reason valid with many authorization server's supporting the prompt=none query parameter to the /authorize endpoint? If the user has an active session with the authorization server, no prompts for user consent are shown.

[AndrewBourgeois]

Your example uses the Token endpoint to show that a refresh token is sent either way. But isn't that controlled by the offline_access scope that you send to the Authorize endpoint?

[DaImTo]

Yes it is! some of the client libraries add this internally you dont even see it happening.

[Philip Couling]

Note that in your comment about "the truth about offline access" that the client has to go back to the authentication server (google) to use it. Having a refresh token doesn't garentee the refresh request will be granted if the user has dropped offline. It's needed for online access or the user would have to login every hour. If an application goes rogue and and begins accessing user data without them present (without permission) it risks detection by google or the user themselves which may violate terms of service.