This document discusses using Doorkeeper and OAuth 2.0 to protect APIs. It provides an overview of OAuth concepts like access tokens, scopes, applications, roles, and grant types. It then covers setting up Doorkeeper, including defining scopes, protecting controllers, handling user groups, password resets, and testing. Real-world uses of OAuth like email logins, first-party apps, third-party apps, native apps, and API documentation are also mentioned.

1. Mads Jensen
Protecting your APIs with
Doorkeeper and OAuth 2.0
aarhus.rb 11/04-2018

2. • SaaS business based in Silkeborg
• Loves Ruby on Rails

3. Definition
• “Who are you?”
• Establishing identity
• 401 Unauthorized
• “Can you do this?”
• Verifying access
• 403 Forbidden
Authentication Authorization

4. • Alternative to session cookies
• Embraces HTTP statelessness
• You don’t to have to worry about CSRF
• Ajax/SPA friendly
• Authorization: Bearer <token>
Token Based Authentication

5. API-first mindset
Your web appYour App
3rd party
cloud service
API

6. Part I: Introduction to
OAuth 2

7. Access Tokens Scopes ApplicationsRoles
Concepts

8. Access Tokens Scopes ApplicationsRoles
Concepts
Resource Owner Client Resource Server Authorization Server
“End-user” when
referring to a person
Capable of granting
access to protected
resource
The application
making
requests/accesses
the protected
resource on behalf
of the user
The server hosting
the protected
resource
The server issuing
access tokens to the
Client
Often same server
as the Resource
Server

9. Access Tokens
• Access tokens are often randomly generated strings,
opaque to the client
• Associated with a set of scopes
• Has a limited lifetime
• Can be made self contained with JWT
Scopes ApplicationsRoles
Concepts

10. Access Tokens Scopes ApplicationsRoles
Concepts
• Scopes define capabilities in your system
• Often divided in *_read and *_write
• Using scoped access token make it possible to create
levels of privileges

11. Access Tokens Scopes ApplicationsRoles
Concepts
• Represent a 3rd party
• Has client_id and client_secret
• Public or Confidential
• Must provide a Redirect URI

12. Protocol Overview
Client
(Application)
Owner
(End-user)
Auth Server
Resource
Server
Authorization request
Authorization grant
Authorization grant
Access Token
Access Token
Protected Resource

13. Authorization Prompt

14. Grant Types
Authorization Code Most used
Implicit Not recommended
Resource Owner
Password
Use only for 1st party
apps
Client Credentials
Lets the Application acts
on behalf of it self

15. Authorization Code Grant
Client
(Application)
Owner
(End-user)
Auth/Resource
Server
(Service API)
User-Agent
(Browser)
1. User Authorization Request
2. User Authorizes Application
3. Authorization Code Grant
4. Access Token Request
5. Access Token Grant

16. Endpoints
GET /authorize
Returns a human-friendly HTML page
with an “Authorize” and an “Decline”
button. Should somehow redirect user
POST /authorize
Used to obtain authorization grant via
user-agent redirect
POST /token
Used to exchange authorization grant
into access token
GET Client Redirect Endpoint
Where user-agent should redirect to after
/authorize

17. HTTP Requests
GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Server Client

18. • Token are issued with a limited life time
• Issued alongside access tokens
• Refresh tokens can be exchanged for new access tokens
• client_id and client_secret needed to refresh
• Uses the refresh_token grant type
Refresh tokens

19. Grants for Native Apps
• Possible to redirect from browser to native app, e.g.
webshipr://authorized
• Client secret cannot be used
• The Proof Key for Code Exchange (“pixie”) is an extension
to Authorization Code grant type

20. Grants for Native Apps
Source: The PKCE specification

21. Part II: Setting up
Doorkeeper

22. Doorkeeper

23. Defining Scopes

24. Protecting Controller
class BaseController < ActionController
before_action :doorkeeper_authorize!
end

25. Protecting Controller
class PostsController < BaseController
before_action -> {
doorkeeper_authorize! :read_posts
}, only: [:index, :show]
before_action -> {
doorkeeper_authorize! :write_posts
}, only: [:create, :delete, :update]
end

26. Handling User groups
• Business decision: Password grant tokens inherits scopes
from user group
• Business decision: Grant type authorization code can
elevate scopes

27. Handling User Groups

28. • Confirmation email on create
• Custom logic for password reset token and confirmation
email
• Special scope write_reset_password for setting password
Password Resets

29. Password Resets

30. Password Resets

31. • Test before_action validation with type: :request
• Test type: :controller with sign_in helper
Testing with RSpec

32. Testing with RSpec

33. Real world uses
• Email/password logins
• 1st party applications
• 3rd party applications
• Native applications
• Mobile apps
• API explorer in docs

34. The OAuth 2.0 Authorization Framework
https://tools.ietf.org/html/rfc6749
https://oauth.net/
An Introduction to OAuth 2
https://www.digitalocean.com/community/tutorials/an-introduction-to-
oauth-2
OAuth 2.0 Threat Model and Security Considerations
https://tools.ietf.org/html/rfc6819
Doorkeeper Github repo
https://github.com/doorkeeper-gem/doorkeeper
References

35. Questions?