How to validate an OAuth 2.0 access token for a resource server?

Question

When a client asks a resource server to get a protected resource with an OAuth 2.0 access token, how does this server validate the token? The OAuth 2.0 refresh token protocol?

The server is supposed to be able to validate the token it has previously issued itself... Usually this will be a database lookup or crypto (self-signed tokens). — Thilo, Sep 06 '12 at 08:35
I see. How about this case, the resource owner WS and client WS are both on difference devices? — Ack, Sep 06 '12 at 08:47
You mean the authentication service and the resource service? (the client/consumer will always be on a different device, and cannot validate tokens himself) If that is the case, you can use refresh tokens that are "expensive" to check (only auth server can do it) but long-lived and access tokens that expire frequently and can be checked offline. — Thilo, Sep 06 '12 at 08:50
http://blog.facilelogin.com/2016/03/adding-oauth-20-token-introspection.html — Prabath Siriwardena, Mar 08 '16 at 12:57

score 143 · Answer 1 · edited May 01 '19 at 00:50

Google way

Google Oauth2 Token Validation

Request:

https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=1/fFBGRNJru1FQd44AzqT3Zg

Respond:

{
  "audience":"8819981768.apps.googleusercontent.com",
  "user_id":"123456789",
  "scope":"https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "expires_in":436
}

Microsoft way

Microsoft - Oauth2 check an authorization

Github way

Github - Oauth2 check an authorization

Request:

GET /applications/:client_id/tokens/:access_token

Respond:

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "user": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.github.com/users/octocat"
  }
}

Amazon way

Login With Amazon - Developer Guide (Dec. 2015, page 21)

Request :

https://api.amazon.com/auth/O2/tokeninfo?access_token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...

Response :

HTTP/l.l 200 OK
Date: Fri, 3l May 20l3 23:22:l0 GMT 
x-amzn-RequestId: eb5be423-ca48-lle2-84ad-5775f45l4b09 
Content-Type: application/json 
Content-Length: 247 

{ 
  "iss":"https://www.amazon.com", 
  "user_id": "amznl.account.K2LI23KL2LK2", 
  "aud": "amznl.oa2-client.ASFWDFBRN", 
  "app_id": "amznl.application.436457DFHDH", 
  "exp": 3597, 
  "iat": l3ll280970
}

@gustavodiazjaimes It doesn’t explain at all how server side recognize assigned user id from a token. — user2284570, May 29 '17 at 21:47
I don't understand all the up votes. This doesn't appear to answer the question. — Duncan Jones, Jul 10 '17 at 08:14
Does anybody know if Azure Active Directory has a similar endpoint to check if an issued token is valid? — user180940, Jan 26 '18 at 15:01
google seems to have substantially changed the way oauth2 tokens are managed and your url no longer works. Could you update this answer please? — deltree, Aug 28 '20 at 16:57

score 119 · Accepted Answer · edited Oct 07 '21 at 07:34

119

Update Nov. 2015: As per Hans Z. below - this is now indeed defined as part of RFC 7662.

Original Answer: The OAuth 2.0 spec (RFC 6749) doesn't clearly define the interaction between a Resource Server (RS) and Authorization Server (AS) for access token (AT) validation. It really depends on the AS's token format/strategy - some tokens are self-contained (like JSON Web Tokens) while others may be similar to a session cookie in that they just reference information held server side back at the AS.

There has been some discussion in the OAuth Working Group about creating a standard way for an RS to communicate with the AS for AT validation. My company (Ping Identity) has come up with one such approach for our commercial OAuth AS (PingFederate): https://support.pingidentity.com/s/document-item?bundleId=pingfederate-93&topicId=lzn1564003025072.html#lzn1564003025072__section_N10578_N1002A_N10001. It uses REST based interaction for this that is very complementary to OAuth 2.0.

edited Oct 07 '21 at 07:34

Community

1
1

answered Sep 06 '12 at 19:20

Scott T.

6,152
1
26
32

Scott T , Is there a way to see a code sample on how to utilize the feature in Ping Federate? – JavaHead Feb 13 '17 at 23:57
2

@JavaHead there are some more protocol details covered on our developer web site here: https://developer.pingidentity.com/en/resources/oauth-2-0-developers-guide.html#validate_token.

Additionally, the PingFederate OAuth Playground ships as a set of JSPs that can be referenced as source code for validating tokens. It (and other open source libraries and samples) can be downloaded from here: https://developer.pingidentity.com/en/code.html – Scott T. Feb 14 '17 at 17:00
Scott, I am looking for a sample that would demonstrate Client Credentials Grant with Rest API protected by a local Resource Server and PingFederate as the Auth Server. The local resource server will then call the validation endpoint. Have you come across anything like that? – JavaHead Feb 14 '17 at 20:33
@JavaHead again that's something you should be able to reference the PingFederate OAuth Playground for. It demonstrates both the Client Credentials Grant Type and validation of an Access Token by a Resource Server. – Scott T. Feb 14 '17 at 22:28
In the case of a JWT access token, I would assume you typically would not want to hit the AS introspection endpoint for every incoming request to the RS. In which case, is an RS check of token signature and scope enough? Or, perhaps the RS could cache the introspection responses from the AS for some amount of time? – Gary Sep 01 '18 at 00:58
1

@Gary You're correct, but ultimately it depends on implementation and the features of the AS. The AS may still have some capability to revoke the Access Token, in which case you might want to call back to ensure that is checked. An expiry and signature check wouldn't tell you the AT should still be treated as valid. – Scott T. Sep 01 '18 at 03:33

score 65 · Answer 3 · edited Oct 07 '21 at 07:34

65

An update on @Scott T.'s answer: the interface between Resource Server and Authorization Server for token validation was standardized in IETF RFC 7662 in October 2015, see: https://www.rfc-editor.org/rfc/rfc7662. A sample validation call would look like:

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483

token=2YotnFZFEjr1zCsicMWpAA

and a sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "client_id": "l238j323ds-23ij4",
  "username": "jdoe",
  "scope": "read write dolphin",
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "iss": "https://server.example.com/",
  "exp": 1419356238,
  "iat": 1419350238,
  "extension_field": "twenty-seven"
}

Of course adoption by vendors and products will have to happen over time.

edited Oct 07 '21 at 07:34

Community

1
1

answered Jan 20 '15 at 14:47

Hans Z.

50,496
12
102
115

If using OoenId Connect shouldn't we prefer openid way of using id token to validate access token: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitTokenValidation – adnan kamili Jan 13 '17 at 10:34
1

@Renan: to be in line with the way scopes are requested in an authorization request, which is with a `scope` query parameter whose value contains a space-separated list of scopes – Hans Z. May 20 '17 at 20:30
6

Please do not use the word "standardized" when something hasn't officially been accepted by a governing body. The IETF RFC 7662 as of Feb 2018 clearly indicates that it is a "proposal". – Johann Feb 01 '18 at 08:17
6

@adnankamili There is no such thing as a "proposal". By the time a document becomes an RFC it is already a "proposed standard" which carries significant weight behind it. OAuth 2.0 itself is still a "proposed standard" so I'm not certain what point you are trying to make. – Pace Mar 04 '19 at 21:11
If OAuth is considered a "3-leg" authentication, would this introspect call be the 3rd leg? I mis-attributed the "3rd leg" to Client calling Authorization Server to exchange the auth code for the access token. – eel ghEEz Dec 22 '20 at 19:39
related question https://stackoverflow.com/questions/71686620/debugging-the-interface-between-resource-server-and-authorization-server-valida – ses Mar 31 '22 at 03:49

score 25 · Answer 4 · edited May 06 '17 at 16:37

OAuth 2.0 spec doesn't define the part. But there could be couple of options:

When resource server gets the token in the Authz Header then it calls the validate/introspect API on Authz server to validate the token. Here Authz server might validate it either from using DB Store or verifying the signature and certain attributes. As part of response, it decodes the token and sends the actual data of token along with remaining expiry time.
Authz Server can encrpt/sign the token using private key and then publickey/cert can be given to Resource Server. When resource server gets the token, it either decrypts/verifies signature to verify the token. Takes the content out and processes the token. It then can either provide access or reject.

score 11 · Answer 5 · answered May 10 '21 at 11:11

Updated Answer for 2021

It is generally not recommended that you roll any part of the OAuth 2 / OIDC implementation on your own, especially now that token introspection is part of the standard. Much like attempting to roll your own encryption library, it is far too easy to make critical mistakes with such a complex spec.

Here's a list of recommended libraries in other languages that implement OAuth 2. Here's another of ones that have been certified by the OpenID Foundation; many of those libraries also implement OAuth 2.

If you're in .NET and using the IdentityServer library (version 2.2 and up), the introspect endpoint accomplishes exactly this. It's published as part of the discovery document (also standard), and is an endpoint against which the resource server can validate access tokens.

If you've come this far and you still really want to roll your own, take some tips from how the bigger libraries have done it.

Introspect endpoint requires client credentials (clientID and secret) to return the response. How would you use it in the apps that cannot keep the secret value (SPA, native apps)? — umat, Oct 26 '22 at 08:42
The introspect client is used by the API/resource server to determine if a token passed to it by a client (SPA, native apps, etc.) is considered valid. It's really only needed if the authorization server and API/resource server are two separate entities (they are often the same). I can't envision a scenario when a client would need to use introspection. As an alternative, the API/resource server can always simply request the public token signing certificate and perform its own validation. I believe that request can be made without authentication. — J.D. Mallen, Oct 27 '22 at 10:02

score 9 · Answer 6 · edited May 06 '17 at 16:37

9

OAuth v2 specs indicates:

Access token attributes and the methods used to access protected resources are beyond the scope of this specification and are defined by companion specifications.

My Authorisation Server has a webservice (SOAP) endpoint that allows the Resource Server to know whether the access_token is valid.

edited May 06 '17 at 16:37

Jonathan Hall

75,165
16
143
189

answered Jul 01 '13 at 12:04

Carlos AG

1,078
1
12
16

How to validate an OAuth 2.0 access token for a resource server?

6 Answers6

Google way

Microsoft way

Github way

Amazon way

Updated Answer for 2021

Linked

Related