The document provides an overview of protecting web APIs using OAuth 2.0, focusing on the use of bearer tokens to authenticate requests. It details the handling of token statuses such as missing, invalid, or insufficient privileges, and outlines two types of token encodings. Additionally, it covers the OAuth 2.0 grant types, the role of authorization servers in issuing tokens, and introduces OpenID Connect as an identity layer on top of OAuth 2.0.

1. Protecting web APIs with
OAuth 2.0
Vladimir Dzhuvinov

2. Bearer Token
Your cool web API

3. HTTPS request with a bearer token
GET /client-reg HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
type token value

4. Successful HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{ … }

5. On missing token
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

6. On invalid / expired token
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error=”invalid_token”

7. On token with insufficient
privileges
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error=”insufficient_scope”

8. To learn more about
bearer token usage
See RFC 6750
[ http://tools.ietf.org/html/rfc6750 ]

9. How does your web API
decode the access tokens?
Your W eb API

10. Typical authorisation attributes
associated with an access token
● Scope: e.g. read,
write, admin...
● Expiration time
● User ID
● Client ID
● Issuer

11. The 2 possible token encodings
● Self-contained:
– Require RSA signature
verification, < 1 ms
– Scale extremely well
● Identifier-based:
– Require web API
lookup, ~100+ ms
– Don't scale well, avoid

12. JSON Web Tokens (JWT)
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzY3AiOlsib3BlbmlkIiwiZW1haWwiLCJwcm
9maWxlIl0sImV4cCI6MTQxNDA2NTEzNCwic3ViIjoiYWxpY2UiLCJpc3MiOiJodHRw
OlwvXC9sb2NhbGhvc3Q6ODA4MFwvYzJpZCIsImlhdCI6MTQxNDA2NDUzNCwiY2l
kIjoiMDAwMTIzIn0.fBZW6U9r7M53fwhoEtC9Bxi8U1ytQvpy8pmHylvvvhEZimluNkw
mDXWIoHuXIgX9ZfqMp9layftbFE7DVeo3wDpGNM9UtOo8Ccpv7rKrcN60ai6G2hop
e7sCRvWTqYx2g8Mk7UOT061Feei7RMYFekO5pFPxSDiKyHCQjbkU
Syntax:
BASE64URL(header) +
“.” +
BASE64URL(JSON-claims) +
“.” +
BASE64URL(RSA-signature)

13. JSON Web Tokens (JWT)
Header
{ "alg": "RS256", "kid": "1" }
Claims
{ "sub": "alice",
"cid": "000123",
"iss": "https://connect2id.com",
"exp": 1414065134,
"iat": 1414064534,
"scp": [ "read", "write", "admin" ]
}
Signature (RSA)
fBZW6U9r7M53fwh­oEtC9
Bxi8U1ytQvpy8pmHylvvvhEZimlu­NkwmDXWIoHuXIgX9ZfqMp9layftbFE7DVeo­3wDpGNM9UtOo8Cc

14. To learn more about JWT
See draft-ietf-oauth-json-web-token-29
[ http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-29 ]

15. The ultimate Java library for JWT
http://connect2id.com/products/nimbus-jose-jwt
Thousands of deployments, tens of reviewers and
contributors
Connect2id, Mitre Corp, Microsoft, EA, Square, Zendesk,
CertiVox, Harvard Medical Schools, unnamed banks, etc.

16. Who issues the access tokens?

17. Your authorisation server
Authenticates
users and clients,
issues tokens
OAuth 2.0
server
mobile app
web app
native app
Web API Web API Web API
Web APIs service requests, need only understand access tokens

18. The OAuth 2.0 grants
● Authorisation code – require browser for end-user
interaction
● Implicit – for browser (JS) based apps
● Password – for native apps
● Client credentials – for clients acting on their own
behalf
● Assertions:
– SAML 2.0 Bearer
– JWT Bearer

19. To learn more about OAuth 2.0
See RFC 6749
[ http://tools.ietf.org/html/rfc6749 ]

20. OpenID Connect
● Identity layer on top of the OAuth 2.0 framework
● The server issues an ID token in addition to the
access token:
– The ID token is a signed JWT with claims:
● Subject – the end-user ID
● Issuer – the authority
● Issue and expiration date
● Audience – the intended recipients
● Authentication strength and methods

21. ID token claims
{
"sub" : "alice",
"iss" : "https://connect2id.com",
"iat" : 1414076589,
"exp" : 1414077489,
"aud" : [ "000123" ],
"ip_address" : "10.20.30.40",
"acr" : "1",
"amr" : [ "ldap" ]
}

22. To learn more about
OpenID Connect
See
OpenID Connect 1.0 Core
OpenID Connect 1.0 Discovery
OpenID Connect 1.0 Dynamic Registration
OpenID Connect 1.0 Session Management
[ http://openid.net/connect/ ]