Data Modelling and Identity Management with OAuth2

The OAuth2 specification (wisely) leaves a lot of areas open to interpretation and implementation details, so there are a lot of opportunities to impose interpretations on the flows and the underlying data. This presentation starts with a basic guide to the main features of OAuth2 and then goes on to show, with examples, how they can be exploited to support business and application use cases. For instance, should you encode access decision data directly in the access token, or make the token completely opaque? Should you be signing requests? What naming convention should you use for OAuth2 scopes? How do you go about registering users and clients? There are some obvious patterns in existing OAuth2 implementations, and Spring Security OAuth provides plenty of hooks and extension points should you wish to copy one of those, or make your own rules.

keywords: @spring, @springcentral, @oauth, @security

Transcript

1. Data Modelling for OAuth2
   Dave Syer, 2013
   Twitter: @david_syer
   Email: dsyer@gopivotal.com
   

   View Slide

2. View Slide

3. Agenda
   Quick overview of OAuth2?
   Data Modelling for OAuth2
   Spring OAuth
   Cloud Foundry UAA
   

   View Slide

4. Quick Introduction to OAuth2
   A Client application, often web application, acts on behalf of a User, but with 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
   

   View Slide

5. OAuth2 Key Features
   Extremely simple for clients
   Access tokens carry information (beyond identity)
   Resource Servers are free to interpret tokens
   Example token contents:
   Client id
   Resource id (audience)
   User id
   Role assignments
   

   View Slide

6. Obtaining a Client Token
   A client can act its own behalf (client_credentials grant):
   

   View Slide

7. Web Application Client
   The Client wants to access a Resource on behalf of the User
   

   View Slide

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

   View Slide

9. Authorization Code Grant
   Summary
   Authorization Server authenticates the User
   1.
   Client starts the authorization flow and obtain User's approval
   2.
   Authorization Server issues an authorization code (opaque one-time token)
   3.
   Client exchanges the authorization code for an access token.
   4.
   

   View Slide

10. 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 " resource.server.com/stuff
    The resource server treats the request as if it came from an authenticated user.
    

    View Slide

11. Role of Client Application
    Register with Authorization Server (get a client_id and maybe a
    client_secret)
    Do not collect user credentials
    Obtain a token (opaque) from Authorization Server
    On its own behalf - client_credentials
    On behalf of a user
    Use it to access Resource Server
    

    View Slide

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

    View Slide

13. Role of the Authorization Server
    Compute token content and grant tokens
    1.
    Interface for users to confirm that they authorize the Client to act on their behalf
    2.
    Authenticate users (/authorize)
    3.
    Authenticate clients (/token)
    4.
    #1 and #4 are covered thoroughly by the spec; #2 and #3 not (for good reasons).
    

    View Slide

14. 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.
    1.0 = Nov 2012
    1.0.5 = Aug 2013
    1.1.0 = soon
    

    View Slide

15. Spring OAuth Responsibilities
    Authorization Server: AuthorizationEndpoint and TokenEndpoint
    Resource Server: OAuth2AuthenticationProcessingFilter
    Client: OAuth2RestTemplate, OAuth2ClientContextFilter
    

    View Slide

16. Spring as Resource Server
    

    View Slide

17. Spring as Authorization Server
    

    View Slide

18. Spring as Client Application
    

    View Slide

19. OAuth2 Data Modelling
    Token format
    Token contents
    Client registrations
    Computing permissions
    User approvals
    User authentication
    

    View Slide

20. Token Format
    OAuth 2.0 tokens are opaque to clients (so might be simple keys to a backend
    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" }
    

    View Slide

21. Token Format Choices
    Resources decode through:
    Shared storage -> opaque
    1.
    Remote service (e.g. /check_token) -> opaque
    2.
    Resources decode locally -> encoded + signed ( + possibly encrypted)
    3.
    #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.
    

    View Slide

22. Token Contents
    Audience
    Scope
    Expiry
    Client details
    Other...
    

    View Slide

23. 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.
    

    View Slide

24. Client Registration Data
    Client id
    Secret
    Redirect URIs
    Authorized grant types
    

    View Slide

25. 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).
    

    View Slide

26. View Slide

27. 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)
    

    View Slide

28. More on Scopes
    Per the spec scopes are arbitrary strings. The Authorization Server and the
    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 given client and
    user based on the requested scope (if any).
    

    View Slide

29. Simple Example of Computed
    Scopes
    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 client
    Not implemented out of the box in Spring OAuth 1.0 (might be in 1.1)
    

    View Slide

30. Cloud Foundry Scope
    Computation
    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 scope names)
    

    View Slide

31. 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"
    }
    ],
    }
    

    View Slide

32. User Approvals
    An access token represents a user approval:
    

    View Slide

33. User Approvals as Token
    An access token represents a user approval:
    

    View Slide

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

    View Slide

35. View Slide

36. Authentication and the
    Authorization Server
    Authentication (checking user credentials) is orthogonal to authorization
    (granting tokens)
    They don't have to be handled in the same component of a large system
    Authentication is often deferred to existing systems (SSO)
    Authorization Server has to be able to authenticate the OAuth endpoints
    (/authorize and /token)
    It does not have to collect credentials (except for grant_type=password)
    

    View Slide

37. Cloud Foundry UAA Authorization
    Server
    

    View Slide

38. 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:
    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.
    

    View Slide

39. Spring OAuth Strategies
    TokenEnhancer - modify token contents
    UserApprovalHandler - decide if authorization request has been approved
    AuthorizationRequestManager (OAuth2RequestFactory and
    OAuth2RequestValidator in 1.1)
    TokenStore - backend store for opaque tokens
    ApprovalStore - new in 1.1
    Higher level:
    AuthorizationServerTokenServices - create and refresh tokens
    ResourceServerTokenServices - decode token
    ConsumerTokenServices - manage token grants and revokes
    

    View Slide

40. UAA Strategies
    Implementations of UserApprovalHandler, *TokenServices,
    AuthorizationRequestManager
    UaaUserDatabase
    ScimUserProvisioning, ScimGroupProvisioning
    Custom approvals layer (will be superseded by 1.1)
    Autologin (login-server)
    

    View Slide

41. 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)
    

    View Slide

42. Links
    http://projects.spring.io/spring-security-oauth Documentation
    http://github.com/springsource/spring-security-oauth Spring OAuth on Github
    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
    

    View Slide