Data Modelling for OAuth2

Dave Syer, 2013
Twitter: @david_syer

Spring IO


Quick Introduction to OAuth2

A Client application, often web application, acts on behalf of a User, but with the User's approval

Common examples of Authorization Servers on the internet:

OAuth2 Key Features

Obtaining a Client Token

A client can act its own behalf (client_credentials grant):


Web Application Client

The Client wants to access a Resource on behalf of the User


Obtaining a User Token

A client can act on behalf of a user (e.g. authorization_code grant):


Authorization Code Grant Summary

  1. Authorization Server authenticates the User

  2. Client starts the authorization flow and obtain User's approval

  3. Authorization Server issues an authorization code (opaque one-time token)

  4. Client exchanges the authorization code for an access token.

OAuth2 Bearer Tokens

Bearer tokens are authentication tokens for client applications. Once you have one you can act on behalf of a user, accessing resources:

$ curl -H "Authorization: Bearer <token>"

The resource server treats the request as if it came from an authenticated user.

Role of Client Application

Role of Resource Server

  1. Extract token from request and decode it
  2. Make access control decision
    • Scope
    • Audience
    • User account information (id, roles etc.)
    • Client information (id, roles etc.)
  3. Send 403 (FORBIDDEN) if token not sufficient

Role of the Authorization Server

  1. Compute token content and grant tokens
  2. Interface for users to confirm that they authorize the Client to act on their behalf
  3. Authenticate users (/authorize)
  4. Authenticate clients (/token)

#1 and #4 are covered thoroughly by the spec; #2 and #3 not (for good reasons).

Spring Security OAuth2

Goal: implement Resource Server, Authorization Server, and Client Application with sensible defaults and plenty of customization choices. Provides features for implementing both consumers and providers of the OAuth protocols using standard Spring and Spring Security programming models and configuration idioms.

Spring OAuth Responsibilities

Spring as Resource Server


Spring as Authorization Server


Spring as Client Application


OAuth2 Data Modelling

Token Format

{  "client_id":"vmc",
 "jti":"f724ae9a-7c6f-41f2-9c4a-526cea84e614" }

Token Format Choices

Resources decode through:

  1. Shared storage -> opaque
  2. Remote service (e.g. /check_token) -> opaque
  3. Resources decode locally -> encoded + signed ( + possibly encrypted)

#2 and #3 require key management infrastructure - resource server and authorization server need to agree on signing (and possibly encryption). Can be as simple as shared configuration file.

Token Contents

Token Audience

Resource Servers should check if they are the intended recipient of a token. No specific mechanism in OAuth2 spec.

In Spring OAuth every resource optionally has a "resource ID". It is copmared with the token in an authentication filter.

For encoded tokens, e.g. JWT has a standard field aud for the audience of the token.

Client Registration Data

Client Registration Scopes

Clients often act on their own behalf (client_credentials grant), and then the available scopes might be different. In Cloud Foundry we find it useful to distinguish between client scopes (for user tokens) and authorities (for client tokens).


Client Registration Data



More on Scopes

Per the spec scopes are arbitrary strings. The Authorization Server and the Resource Servers agree on the content and meanings.


Authorization Server has to decide whether to grant a token to a given client and user based on the requested scope (if any).

Simple Example of Computed Scopes

Uses Spring Security concept of "authorities" attached to a client

Not implemented out of the box in Spring OAuth 1.0 (might be in 1.1)

Cloud Foundry Scope Computation

Client Token

User Token

UAA Scopes

User Approvals

An access token represents a user approval:


User Approvals as Token

An access token represents a user approval:


Formal Model for User Approvals

It can be an advantage to store individual approvals independently (e.g. for explicit revokes of individual scopes):

Authentication and the Authorization Server

Cloud Foundry UAA Authorization Server


Consumer Side User Authentication

Using OAuth2 for authentication (and SSO)

Authorization Server (typically) provides /userinfo endpoint. Client exchanges a bearer token for some information about the user. Examples:

Beware: no standard data format for user info.

Spring OAuth Strategies

Higher level:

UAA Strategies

Other Token Types

Not to be confused with: