Data Modelling for OAuth2Dave Syer, 2013Twitter: @david_syerEmail: dsyer@gopivotal.com

http://localhost:4000/decks/oauth-model-s2gx.html

1 of 45 10/09/13 18:11

http://localhost:4000/decks/oauth-model-s2gx.html

2 of 45 10/09/13 18:11

Agenda

Quick overview of OAuth2?

Data Modelling for OAuth2

Spring OAuth

Cloud Foundry UAA

http://localhost:4000/decks/oauth-model-s2gx.html

3 of 45 10/09/13 18:11

Quick Introduction to OAuth2

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

Authorization Server

Resource Server

Client application

Common examples of Authorization Servers on the internet:

Facebook - Graph API

Google - Google APIs

Cloud Foundry - Cloud Controller

http://localhost:4000/decks/oauth-model-s2gx.html

4 of 45 10/09/13 18:11

OAuth2 Key Features

Extremely simple for clients

Access tokens carry information (beyond identity)

Resource Servers are free to interpret tokens

Example token contents:Client idResource id (audience)User idRole assignments

http://localhost:4000/decks/oauth-model-s2gx.html

5 of 45 10/09/13 18:11

Obtaining a Client Token

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

http://localhost:4000/decks/oauth-model-s2gx.html

6 of 45 10/09/13 18:11

Web Application Client

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

http://localhost:4000/decks/oauth-model-s2gx.html

7 of 45 10/09/13 18:11

Obtaining a User Token

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

http://localhost:4000/decks/oauth-model-s2gx.html

8 of 45 10/09/13 18:11

Authorization Code GrantSummary

Authorization Server authenticates the User1.

Client starts the authorization flow and obtain User's approval2.

Authorization Server issues an authorization code (opaque one-timetoken)

3.

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

http://localhost:4000/decks/oauth-model-s2gx.html

9 of 45 10/09/13 18:11

OAuth2 Bearer Tokens

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

$ curl -H "Authorization: Bearer <token>" resource.server.com/stuff

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

http://localhost:4000/decks/oauth-model-s2gx.html

10 of 45 10/09/13 18:11

Role of Client Application

Register with Authorization Server (get a client_id and maybe aclient_secret)

Do not collect user credentials

Obtain a token (opaque) from Authorization ServerOn its own behalf - client_credentialsOn behalf of a user

Use it to access Resource Server

http://localhost:4000/decks/oauth-model-s2gx.html

11 of 45 10/09/13 18:11

Role of Resource Server

Extract token from request and decode it1.

Make access control decision

Scope

Audience

User account information (id, roles etc.)

Client information (id, roles etc.)

2.

Send 403 (FORBIDDEN) if token not sufficient3.

http://localhost:4000/decks/oauth-model-s2gx.html

12 of 45 10/09/13 18:11

Role of the AuthorizationServer

Compute token content and grant tokens1.

Interface for users to confirm that they authorize the Client to act ontheir behalf

2.

Authenticate users (/authorize)3.

Authenticate clients (/token)4.

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

http://localhost:4000/decks/oauth-model-s2gx.html

13 of 45 10/09/13 18:11

Spring Security OAuth2

Goal: implement Resource Server, Authorization Server, and ClientApplication with sensible defaults and plenty of customization choices.Provides features for implementing both consumers and providers of theOAuth protocols using standard Spring and Spring Security programmingmodels and configuration idioms.

1.0 = Nov 2012

1.0.5 = Aug 2013

1.1.0 = soon

http://localhost:4000/decks/oauth-model-s2gx.html

14 of 45 10/09/13 18:11

Spring OAuth Responsibilities

Authorization Server: AuthorizationEndpoint andTokenEndpoint

Resource Server: OAuth2AuthenticationProcessingFilter

Client: OAuth2RestTemplate, OAuth2ClientContextFilter

http://localhost:4000/decks/oauth-model-s2gx.html

15 of 45 10/09/13 18:11

Spring as Resource Server

http://localhost:4000/decks/oauth-model-s2gx.html

16 of 45 10/09/13 18:11

Spring as AuthorizationServer

http://localhost:4000/decks/oauth-model-s2gx.html

17 of 45 10/09/13 18:11

http://localhost:4000/decks/oauth-model-s2gx.html

18 of 45 10/09/13 18:11

Spring as Client Application

http://localhost:4000/decks/oauth-model-s2gx.html

19 of 45 10/09/13 18:11

OAuth2 Data Modelling

Token format

Token contents

Client registrations

Computing permissions

User approvals

User authentication

http://localhost:4000/decks/oauth-model-s2gx.html

20 of 45 10/09/13 18:11

Token Format

OAuth 2.0 tokens are opaque to clients (so might be simple keys to abackend store)

But they carry important information to Resource Servers

Example implementation (from Cloud Foundry UAA, JWT = signed,base64-encoded, JSON):

{ "client_id":"vmc", "exp":1346325625, "scope":["cloud_controller.read","openid","password.write"], "aud":["openid","cloud_controller","password"], "user_name":"vcap_tester@vmware.com", "user_id":"52147673-9d60-4674-a6d9-225b94d7a64e", "email":"vcap_tester@vmware.com","jti":"f724ae9a-7c6f-41f2-9c4a-526cea84e614" }

http://localhost:4000/decks/oauth-model-s2gx.html

21 of 45 10/09/13 18:11

Token Format Choices

Resources decode through:

Shared storage -> opaque1.

Remote service (e.g. /check_token) -> opaque2.

Resources decode locally -> encoded + signed ( + possiblyencrypted)

3.

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

http://localhost:4000/decks/oauth-model-s2gx.html

22 of 45 10/09/13 18:11

Token Contents

Audience

Scope

Expiry

Client details

Other...

http://localhost:4000/decks/oauth-model-s2gx.html

23 of 45 10/09/13 18:11

Token Audience

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

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

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

http://localhost:4000/decks/oauth-model-s2gx.html

24 of 45 10/09/13 18:11

Client Registration Data

Client id

Secret

Redirect URIs

Authorized grant types

http://localhost:4000/decks/oauth-model-s2gx.html

25 of 45 10/09/13 18:11

Client Registration Scopes

Clients often act on their own behalf (client_credentials grant), andthen the available scopes might be different. In Cloud Foundry we find ituseful to distinguish between client scopes (for user tokens) andauthorities (for client tokens).

http://localhost:4000/decks/oauth-model-s2gx.html

26 of 45 10/09/13 18:11

http://localhost:4000/decks/oauth-model-s2gx.html

27 of 45 10/09/13 18:11

Client Registration Data

Minimum

Client id

Secret

Redirect URIs

Authorized grant types

Desirable

Authorities -> scope for client token

Default scopes -> scope for user token

Resource ids -> audience

Owner of registration (e.g. a user)

http://localhost:4000/decks/oauth-model-s2gx.html

28 of 45 10/09/13 18:11

More on Scopes

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

Examples:

Google: https://www.googleapis.com/auth/userinfo.profile

Facebook: email, read_stream, write_stream

UAA: cloud_controller.read, cloud_controller.write,scim.read, openid

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

http://localhost:4000/decks/oauth-model-s2gx.html

29 of 45 10/09/13 18:11

Simple Example of ComputedScopes

Client requests scope=read,write

Auth server compares client authorities=read

Grants token with narrower scope

Uses Spring Security concept of "authorities" attached to a clientNot implemented out of the box in Spring OAuth 1.0 (might be in 1.1)

http://localhost:4000/decks/oauth-model-s2gx.html

30 of 45 10/09/13 18:11

Cloud Foundry ScopeComputation

Client Token

If client requests no explicit scope: set to default value per client

Restrict to intersection with default scopes (per client)

User Token

If client requests no explicit scope: set to default value per client

Restrict to intersection with default scopes (per client)

Further restrict to intersection with user groups (same as scopenames)

http://localhost:4000/decks/oauth-model-s2gx.html

31 of 45 10/09/13 18:11

UAA Scopes

UAA scopes are actually Groups in the User accounts

GET /Groups, Get /Users/{id}

{ "id": "73ba999e-fc34-49eb-ac26-dc8be52c1d82", "meta": {...}, "userName": "marissa", "groups": [ ... { "value": "23a71835-c7ce-43ac-b511-c84d3ae8e788", "display": "uaa.user", "membershipType": "DIRECT" } ],}

http://localhost:4000/decks/oauth-model-s2gx.html

32 of 45 10/09/13 18:11

User Approvals

An access token represents a user approval:

http://localhost:4000/decks/oauth-model-s2gx.html

33 of 45 10/09/13 18:11

http://localhost:4000/decks/oauth-model-s2gx.html

34 of 45 10/09/13 18:11

User Approvals as Token

An access token represents a user approval:

http://localhost:4000/decks/oauth-model-s2gx.html

35 of 45 10/09/13 18:11

http://localhost:4000/decks/oauth-model-s2gx.html

36 of 45 10/09/13 18:11

Formal Model for UserApprovals

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

http://localhost:4000/decks/oauth-model-s2gx.html

37 of 45 10/09/13 18:11

http://localhost:4000/decks/oauth-model-s2gx.html

38 of 45 10/09/13 18:11

Authentication and theAuthorization Server

Authentication (checking user credentials) is orthogonal toauthorization (granting tokens)

They don't have to be handled in the same component of a largesystem

Authentication is often deferred to existing systems (SSO)

Authorization Server has to be able to authenticate the OAuthendpoints (/authorize and /token)

It does not have to collect credentials (except forgrant_type=password)

http://localhost:4000/decks/oauth-model-s2gx.html

39 of 45 10/09/13 18:11

Cloud Foundry UAAAuthorization Server

http://localhost:4000/decks/oauth-model-s2gx.html

40 of 45 10/09/13 18:11

Consumer Side UserAuthentication

Using OAuth2 for authentication (and SSO)

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

Github: https://api.github.com/user

Facebook: https://graph.facebook.com/me

Cloud Foundry: https://uaa.run.pivotal.io/userinfo

Beware: no standard data format for user info.

http://localhost:4000/decks/oauth-model-s2gx.html

41 of 45 10/09/13 18:11

Spring OAuth Strategies

TokenEnhancer - modify token contents

UserApprovalHandler - decide if authorization request has beenapproved

AuthorizationRequestManager (OAuth2RequestFactory andOAuth2RequestValidator in 1.1)

TokenStore - backend store for opaque tokens

ApprovalStore - new in 1.1

Higher level:

AuthorizationServerTokenServices - create and refreshtokens

ResourceServerTokenServices - decode token

ConsumerTokenServices - manage token grants and revokes

http://localhost:4000/decks/oauth-model-s2gx.html

42 of 45 10/09/13 18:11

UAA Strategies

Implementations of UserApprovalHandler, *TokenServices,AuthorizationRequestManager

UaaUserDatabase

ScimUserProvisioning, ScimGroupProvisioning

Custom approvals layer (will be superseded by 1.1)

Autologin (login-server)

http://localhost:4000/decks/oauth-model-s2gx.html

43 of 45 10/09/13 18:11

Other Token Types

OpenID connect. Simple view: add id_token to access token.

MAC Tokens. Simple view: sign token with hash of request.

Not to be confused with:

grant types (e.g. exchange SAML assertion for token),

authentication channels (e.g. LDAP authentication for users)

http://localhost:4000/decks/oauth-model-s2gx.html

44 of 45 10/09/13 18:11

Links

http://projects.spring.io/spring-security-oauth Documentation

http://github.com/springsource/spring-security-oauth Spring OAuth onGithub

http://github.com/cloudfoundry/uaa UAA on Github (see docs/ folder)

http://blog.cloudfoundry.org

http://spring.io/blog

http://dsyer.com/presos/decks/oauth-model-s2gx.html

Twitter: @david_syer

Email: dsyer@gopivotal.com

http://localhost:4000/decks/oauth-model-s2gx.html

45 of 45 10/09/13 18:11