OAuth

• Concepts
• Roles:
  • Authorization Server: server that issues authorization token
  • Resource Owner: Application's end-user that grants permission to access resources
  • Resource Server: holds resources that lets a client use resources upon valid access token
  • Client: The application that needs to access resources and requests access token from authorization server and passes to resource server
    1. Confidential: A client that can safely store its secret
       • Web app using Authorization Code, Resource Owner flows
       • Machine-to-Machine using Client Credential flow
    2. Public: cannot safely store secret.
       • Native or Mobile App using Authorization Code with PKCE
       • SPA using Implicit flow
• scope: names of specific resources that the client is requesting access to. These are Arbitrary strings that authorization server and the client understand
• grant: is the authorization given to the client by the user. E.g.: authorization-code or client-credential
• Tokens
  1. authorization token: issued when authorization authenticates and authorizes resource owner. It has a short life and can only be used to exchange it for an access token
  2. refresh token: is an optional token, it is usually issued at authorization along with authorization token. It can only be used to exchange it for an access token. A refresh token maybe exchanged multiple times, or the client may receive a new refresh token with each exchange. It has a longer life (typically months or days)
  3. access token: is issued by authorization-server to the client in exchange for either authorization token or a refresh token. It can be used for access resources owned by the resource-owner. It has a short life (minutes to couple of hours)
• OAuth does not specify the token format, but JWT is the defacto standard
• OAuth does not specify what scopes are valid, it is up to the authorization server to define and enforce them.

OAuth Flows

Main flows

1. Authorization Code Flow
2. Authorization Code Flow with PKCE
3. Client Credential flow
4. Refresh flow
5. Device Grant flow

Authorization Code flow

• Authorization Code: Confidential client (server-side applications)

sequenceDiagram;
    autonumber
    actor O as Resource Owner
    participant C as Client
    participant A as Authorization Server
    participant R as Resource Server

    O->>C: User login
    C->>A: Authorization Code request to /authorize
    A->>O: 302 redirect to authentication prompt
    O->>A: Authentication and consent
    A->>C: Authorization Code response
    C->>A: Send authorization code and client secret to /token
    A->>C: Access token (and optionally refresh token)
    C->>R: Request with access token
    R->>C: Response

Authorization Code flow With PKCE

sequenceDiagram;
    autonumber
    actor O as Resource Owner
    participant C as Client
    participant A as Authorization Server
    participant R as Resource Server

    O->>C: User login
    C->>C: generate code verifier + challenge
    C->>A: Authorization Code request + challenge
    A->>O: 302 redirect to authentication prompt
    O->>A: Authentication and consent
    A->>C: Authorization Code response
    C->>A: Send authorization code + verifier
    A->>A: Validate verifier with challenge
    A->>C: Access token (and optionally refresh token)
    C->>R: Request with access token
    R->>C: Response

• Authorization Code with PKCE: Public client (modern web, native or mobile applications)
• Client has only the client ID, but not the client secret, but uses PKCE to exchange an authorization code with access code
  1. App creates a random secret value called code verifier
  2. create a cryptographic hash called code challenge from code verifier
  3. code challenge is included with authorization request
• code challenge with Authorization Code is sent to Authorization Server for exchanging it with access token
• Authorization Server solves the challenge using agreed upon hash algorithm
• If a rogue application steals authorization code, it won't be able to send the code verifier because both code challenge and code verifier are sent using HTTPS

Client Credential flow

• Client Credentials: server-side Confidential application with no human user.
• Client authenticates as itself using client ID and client secret
• No clear resource owner
• recommended to use only for machine-to-machine communication

Refresh flow

• Client exchanges the refresh token, instead of authorization token, to obtain an access token
• refresh token is obtained along with authorization token as part of initial authorization
• exchanging a refresh token for access token doesn't require resource owner authorization
  • exchange succeeds as long as the resource owner hasn't revoked access
• With each exchange of refresh token with access token, authorization server returns another refresh token, which may be the same refresh token or a different refresh token, which then must be used for the next exchange

Device Grant flow

• used by devices (such as TV) that normally don't have a way to redirect resource owner to authorization server or them to input authentication information
• Devices obtain a random, short-lived code from the authorization server and ask resource owner to validate it at a specific website
• Devices keep polling authorization server until authorization server confirms that the resource owner was authenticated and the random code was entered

Outdated flows

Following flows shouldn't be used because they are considered insecure

Implicit

• Implicit: Public application
• Directly requests access token instead of access code
• Used when the confidentiality of the client-secret can't be guaranteed
• doesn't support refresh-tokens due to less trusted clients

Resource Owner Password

• Resource Owner Password: Confidential clients that have control over the resource
• client can store client secret
• used when you control both client and the resource
• Used by online applications, for example, Facebook client applications that interact with Facebook service