Kinde Guide to OAuth 2.0 flows
Guide to OAuth 2.0 flows
OAuth 2.0 is an industry-standard authorization protocol. OAuth flows are different ways of retrieving Access Tokens. Depending on your app’s needs and requirements, you’ll need to select the right OAuth flow to keep your platform secure and functional.
When considering which OAuth flow to use for your app, there are some important factors to consider which will help you make the right decision, from the kind of user experience you want to deliver to the level of trust with the client.
An introduction to OAuth flows
OAuth 2.0 is an authorization framework that underpins various types of authorization flows. Flows are different methods of redeeming access tokens, the key that allows your app to access an API.
OAuth is an industry-standard authorization protocol that apps use to provide customers with secure delegated access. Plus, it authorizes devices, apps, and application programming interfaces (APIs) by using access tokens instead of credentials.
OAuth flows permit users to enter login credentials through an OAuth login prompt or via back-end systems that don’t require user involvement for authentication.
OAuth 2.0 follows these key roles:
- Resource owner: the entity that grants access to a protected resource, generally, this is the user.
- Resource server: the server hosting the protected resources that the resource owner needs to access. The goal of OAuth is to securely grant access to the resource.
- Client: the app that requests access to the protected resource (a.k.a. the user’s account). Before it can access those resources, it has to be authorized by the user and validated by the API.
- Authorization server: the server that authenticates the resource owner and gives out access tokens to grant access to an app.
OAuth flow types
OAuth flows differ in the way you acquire and validate tokens, meaning each flow type is suited to specific sets of needs and scenarios.
1. Authorization Code Flow
Authorization Code Flow exchanges authorization codes for tokens. For this exchange to work, your app must be server-side because you’re exchanging your app’s Client Secret which has to be stored securely in your client.
The Authorization Code grant type follows these steps:
- The app opens a browser sending the user to the OAuth server.
- The user approves the app’s request following an authorization prompt.
- The user is redirected back to the app with an authorization code.
- The app exchanges the authorization code for an access token.
2. Client Credentials Flow
The Client Credentials Flow allows apps to exchange their Client Secret and Client ID to an authentication server. This authenticates the user without any user involvement and returns a token.
The Client Credentials Flow is typically used for machine-to-machine (M2M) apps like daemons, CLIs, and back-end services. Instead of a user having to request authorization, the system authenticates the app so no username and password credentials are involved in the process.
The Client Credentials Flow type follows these steps:
- The app authenticates the OAuth Authorization Server using the Client ID and Client Secret.
- OAuth Authorization Server validates both the Client ID and the Client Secret.
- An access token is issued to the app.
- This grants permission to access the API with the user account.
3. Resource Owner Password Flow
The Resource Owner Password Flow asks users to enter credentials, including their username and password using an interactive form. In this flow type, credentials are passed on to the back end and can be stored for future use, meaning the app has to be trusted completely with this information.
The Resource Owner Password Flow isn’t generally recommended aside from scenarios where the apps are completely trusted and other types of redirect flows (like the Authorization Code Flow) can’t be used.
The Resource Owner Password Flow type follows these steps:
- The user logs into an app with their login credentials.
- The application stores and forwards the credentials to the OAuth Authorization Server.
- The authorization server validates the credentials and gives out an access token, and sometimes a refresh token too.
- This allows the app to access the API with the user’s credentials.
4. Implicit Flow with Form Post
Implicit Flow with Form Post uses OpenID Connect (OIDC) to execute a web-sign in. The web app solicits and retrieves tokens through the front channel without needing secrets or back-end calls. This type of flow functions like WS-Federation and SAML and doesn’t require you to use, keep, or secure secrets in your app.
Implicit Flow with Form Post is typically used by apps that don’t want to locally store secrets and follows these steps:
- The user logs in to the app.
- The user is redirected to the authorization server which passes along a response type parameter of an ID token that specifies the type of requested credential.
- The authorization server redirects the user to the login and authorization cue.
- The user authenticates using a login option and may be given the option to see a consent page listing the permissions given to the app.
- The authentication server redirects the user to the app with an ID token.
5. Hybrid Flow
The Hybrid Flow is used by apps that can store client secrets securely which provides your app with instant access to an ID token, while simultaneously providing secure retrieval of access and refresh tokens.
For apps that need immediate access to user data on an ongoing basis, the hybrid flow can be handy. The Hybrid Flow is a combination of the Implicit Flow with Form Post and Authorization Code Flow and follows these steps:
- The user logs into an app.
- The app redirects the user to the authorization server passing along an ID token and authorization code.
- The authorization server redirects the user to the login and authorization cue.
- The user authenticates using a login option and may be given the option to see a consent page listing the permissions given to the app.
- The authorization server redirects the user back to the app with an ID token, an authorization code for one-time use, and an authorization token.
- The app then sends a code to the authorization server with the app’s Client ID and Client Secret and the authorization server verifies the Client ID, Client Secret, and code.
- The authorization server provides a second ID Token and Access Token which is used to call an API to access the user’s information.
- The API then grants access to the data requested.
6. Device Authorization Flow
The Device Authorization Flow lets users authenticate without asking for their login credentials which enhances the user experience for devices that don’t provide an easy option to enter text. In this flow, device apps transfer the user’s Client ID to bring about the authentication process and receive a token.
Device Authorization Flow is typically used on Smart TVs which lets you authenticate an app on your TV through your smartphone or laptop.
Device Authorization Flow works using two different pathways. The first pathway occurs on the device that is requesting authorization (for example a smart TV) and the second pathway occurs in the browser.
In the browser code path, the device code is limited to the session in the browser which occurs simultaneously with the device flow path.
7. Authorization Code Flow with PKCE
The Authorization Code Flow with PKCE is created to authenticate public client applications (for example, native and mobile users). This flow uses a proof of key code exchange (PKCE) which is used for public clients because they don’t have a secret, meaning they can’t authenticate themselves.
There are significant security risks when public clients request access tokens that aren’t alleviated by the Authorization Code Flow. For both native and single-page apps, they can’t securely store a Client Secret.
At the start of the flow, the PKCE makes the app produce a random value called a Code Verifier. The app hashes the Code Verifier which results in a Code Challenge that then works as a normal flow plus a Code Challenge.
The Authorization Server then stores the Code Challenge for future verification and redirects back to the app with an authorization code once the user authenticates. The app then asks to exchange the code for tokens, and the authorization server compares the Code Verifier to the hashed value it stored previously.
How to choose the right OAuth flow
There are a bunch of different OAuth flows which all have specific uses for different needs and cases. Picking the right OAuth flow will depend on the app and the specific scenarios and requirements, like the level of trust between the resource owner and client application, and desired user experience.
Is the Client the Resource Owner?
The first thing to consider is whether access to resources is required by a machine or a human. If access is required by a machine, the Client is the same as the Resource Owner so no end-use authorization is required.
In this case, the Client Credentials Flow is preferable.
Is the Client Completely Trusted with User Credentials?
If the end-user has to enter credentials, like their username and password, using an interactive form, which may result in the Resource Owner Password Credentials Grant. Here, the information is sent to the back end so the Client must be trusted entirely.
This type of grant should only be utilized when redirect-based flows like the Authorization Code Flow aren’t applicable. In this case, the Resource Owner Password Flow is the most suitable option.
Is the Client a Web App Executing on the Server?
When the Client is a consistent web app executing on a server, the Authorization Code Flow is the safest flow option.
In this case, the Authorization Code Flow provides an Access Token and an optional Refresh Token to the client directly without passing through the user’s web browser, thus minimizing the chance of exposure.
Is the Client a Single-Page Application?
If the Client is a Single-Page Application (SPA) that runs in a browser that utilizes a scripting language like JavaScript you can choose between the Implicit Flow with Form Post and the Authorization Code Flow with PKCE.
The preferred option is to use Authorization Code Flow with PKCE as the Access Token isn’t displayed on the client side and it can return Refresh Tokens. Alternatively, if your SPA doesn’t require an Access Token you can utilize the Implicit Flow with Form Post.
Is the Client a Native Mobile Application?
The Authorization Code Flow with PKCE is the preferred method if the app is native.
Choosing an OAuth Flow depends on your app’s requirements and the type of app you’re building. These considerations will help you make the right choice.