A GENTLE INTRODUCTION�TO OAUTH2

Fabio, Moratti | Software Architect

AGENDA

1. Why OAuth2
2. OAuth2 elements
3. OAuth2 in action
4. Flows + some details
5. Resources

WHY OAUTH2

CALLING A BACK-END API

​

1. Application asks username & password from the user

​

• Stores credentials and sends them to the API back-end

​

THE PROBLEM

• Giving the password to the application is too risky: the application has full access
• Revoking the access implies changing the password: other apps must reauthenticate
• Not just third-party apps issue: the API can't tell if is called by a legitimate app or not
• Adding features to authentication (MFA, OPT, etc.): forces reimplementation for all apps

BEFORE OAUTH

• The problem exploded with the advent of public APIs
• Different providers (Twitter/Google/Facebook/Yahoo) invented different “standards”
• All approaches worked differently, but all shared the same goal: allow applications to access data from (third party) apps without the users sharing their password.

2007: the first draft of OAuth1 published

2012: OAuth 2.0 Spec finalized

… work continues

WHAT OAUTH SOLVES?

OAuth2 solves the SingleSignOn use case: the user must not share the password with the application

HOW?

Introduces a separate (centralized) service that manages the authentication and redirects the user back to the API: this magically solves all the problems: the application never handles the password and authentication mechanisms are centralized

HOTEL ANALOGY

Front desk checks passport,

gives key card

Reader checks card,

opens room

• The reader on the room door does not know the guest, the clerk knows does

​

• The key can open the SPA’s door or other services

HOTEL ANALOGY

Front desk is the OAuth2 server

The door reader is the back-end API

The key card is the token used for authorization

OAUTH2 ELEMENTS

ROLES

The user: you

The application: running in a back-end server, in the browser or installed on the mobile phone

The device: browser or mobile phone

Authorization Server

Resource Owner

OAuth Client

User Agent

Resource Server

The API or the back-end service

The centralized AOuth2 service that provides authorization

APPLICATIONS CATEGORIES

• First party applications: an app managed by the provider of the user credentials. GMail or Google Drive are Google’s first apps

​

​

• Third party applications: an app managed by a different provider of the user credentials. Authenticating on GitHub or on Flickr using Google or Twitter credentials (Social Login)

APPLICATION TYPES

• The Authorization Server can be sure of the of the app’s identity only for confidential apps
• For public app it must assume that anyone (or anything) is trying to impersonate the app

Confidential: can be deployed with a secret: in practice server-side apps only

Public: cannot be deployed (safely) with a secret: obvious case is SPAs, but mobile apps have the same issue

USER CONSENT

The user consent is provided by the Authorization Server

​

• Interrupts the flow
• Make sure that the user has initiated the authorization process and is in front the application (OAuth Client)
• The password in provided to the Authorization Server, never to the application

FRONT AND BACK CHANNELS

Back Channel is a client / server communication, i.e. HTTPS call that provides:

• server identiy (certificate)
• data secrecy and integrity (encryption)

Front Channel: the communication “bounces” on the user browser address bar via a redirect

• no identity certainty
• no secrecy or integrity

SCOPES

• Scope is a mechanism to limit access to a user’s account
• The application (the OAuth Client) request a list of scopes, the scopes are presented in the user consent screen
• No specification on scope values, the API is free to define the scopes
• Example:
• Access level: Read / Write
• Portion of an API: mail / documents / photos / etc.

APPLICATION REGISTRATION

• The Authorization Server must “register” the applications that will authenticate
• In the registration process the application is configured:
• Confidential / Public:
• App name
• Description / Logo / etc.
• App type: different policies, CORS headers, etc.
• Redirect URLs (beware of wildcards in redirect URL)
• The AS returns:
• Client ID
• Client Secret (optional)

OAUTH IN ACTION

SERVER SIDE APPLICATION

Authorization Server

Resource Owner

OAuth Client

User Agent

Resource Server

Start using the app

Redirect: params + hash

Login + hash

Authorization code

Authorization code

Authorization code + secret

API request + Access Token

Access Token

Generate secret and compute hash (PKCE)

​

Login & consent

Username

Password

Login

Verify secret’s hash

Verify Access Token

API Response

Application Response

SERVER SIDE APPLICATION

• Secret (Code Verifier): random string
• Hash (Code Challenge): base64url(sha256(code_verifier))

https://auth-server.com/auth?� response_type=code&

client_id=<CLIENT_ID>&

redirect_uri=<APP URL>&

scope=<auth scope>&

state=<state>&

code_challenge=<CODE_CHALLENGE>&

code_challenge_method=S256

The link prepared by the app to redirect the user to the AS

• AS endpoint
• this is an authorization code flow (more on this later)
• app identity
• where the user will be redirected
• permissions (more on this later)
• obsoleted by PKCE

Proof Key Code Exchange

SERVER SIDE APPLICATION

https://app.com/redirect?� code=AUTH_CODE&� state=<state>

The link where the user is redirected by the AS

• app redirect endpoint
• valid once auth code
• see previous request

https://auth-server.com/token?� grant_type=authorization_code&

code=<AUTH_CODE>&

redirect_uri=REDIRECT_URI&

code_verifier=VERIFIER_STRING&

client_id=<CLIENT_ID>&

client_secret=<CLIENT_SECRET>

The call from the application to the AS

• AS token end point
• valid once auth code
• Redirect uri used in the request
• The secret whose hash was sent in the auth request
• App identity, this is a confidential app

SERVER SIDE APPLICATION

​

{

“token_type”: “Bearer”,

“access_token”: “<ACCESS_TOKEN>”,

“expires_in”: 3600

“scope”: “<scope>”,

“refresh_token”: “<REFRESH_TOKEN>”

}

​

• Authorization Server token endpoint response: the token is used to make calls to the API back-end.
• The API back-end will need to verify the token validity (more later)
• The refresh token is used to get a new access token when it expires (grant_type=refresh_token)

NATIVE APPLICATIONS

• Native applications are Public clients
• Issues handling the redirect: URL scheme and deep linking
• Need a browser to call the Authorization Server: native browser (outside the application) vs a webview vs SFSafariViewController / Chrome Custom Tabs
• Use the secure storage to handle refresh tokens
• Always use PKCE to mitigate the risks involved with a Public Client

​

The flow is similar to the server side app

SINGLE PAGE APPLICATIONS

• Single page applications are Public clients
• Storing tokens on the browser is not very secure, options are Local Storage, Session Storage, cookies and memory.
• All storage are vulnerable to XSS
• Service Workers: more complicated to use but less prone to XSS attacks
• Use a dynamic back-end to perform the OAuth and then proxy the SPA API requests using the dynamic back-end; SPA – back-end calls are secured by a session cookie

​

The flow is similar to the server side app

IOT DEVICES

• SmartTV, voice activated device, IoT devices
• No browser
• No easy or safe way to input password
• Additionally use a phone or a browser to log-in

DEVICE FLOW

Authorization Server

Resource Owner

OAuth Client

User Agent

Resource Server

Start using the app

Authorization code

Poll for authorization

Login & consent

Username

Password

Login

When user completes authentication

Access Token

User wants to login

Show URL & Code, check every 5 sec.

Go to this URL and enter the code

CLIENT CREDENTIALS

• No user, no browser, no redirect
• Machine to machine communication (e.g. microservices, B2B integrations)
• Client credentials are exchanged for an access token

​

https://auth-server.com/token?� grant_type=client_credentials&

client_id=<CLIENT_ID>&

client_secret=<CLIENT_SECRET>

{

“token_type”: “Bearer”,

“access_token”: “<TOKEN>”,

“expires_in”: 3600

“scope”: “<scope>”

}

TOKENS

• Reference Tokens: opaque (random) id, the data is stored in the Authentication Server
• Self-Encoded Tokens: data is in the token, cryptography (signature) is usually used to make the token secure

​

JWT: common standard to implement self encoded tokens.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

{

"alg": "HS256",

"typ": "JWT"

}

{

"sub": "1234567890",

"name": "John Doe",

"iat": 1516239022

}

Header

Payload

OPEN ID CONNECT

• Access Tokens are opaque for the application, only used for authorization
• The application may need user data: name, email, etc.
• OIDC is an extension of OAuth2 that uses ID Tokens.
• ID Tokens have a JWT format and bear user data
• ID Tokens can be requested along with Access Tokens from the AS

{

"iss": "http://server.example.com",

"sub": "248289761001",

"aud": "s6BhdRkqt3",

"nonce": "n-0S6_WzA2Mj",

"exp": 1311281970,

"iat": 1311280970,

"name": "Jane Doe",

"birthdate": "0000-10-31",

"email": "janedoe@example.com",

}

RESOURCES

RESOURCES

• OAuth2: https://oauth.net / https://oauth.net/specs
• JWT: https://jwt.io
• OKTA: https://www.okta.com
• Auth0: https://auth0.com
• Cognito: https://aws.amazon.com/cognito

THANK YOU