OAuth Application Types

Confidential Vs Public Applications

According to the OAuth 2.0 spec, applications can be classified as either confidential or public. The main difference relates to whether or not the application is able to hold credentials (such as a client ID and secret) securely. This affects the type of authentication the applications can use.

This can be determined based on the Token Endpoint Authentication Method settings.

• None: Public application without a client secret.
• Post: Application using request body parameters to send a client secret.
• Basic: Application using the HTTP BASIC authentication scheme.

Token Endpoint

Get an Access Token in order to call an API. Optionally, you can also retrieve an ID Token and a Refresh Token.

Refresh your Access Token using a Refresh Token you got during authorization.

Confidential Applications

Confidential applications can hold credentials in a secure way without exposing them to unauthorized parties. They require a trusted backend server to store the secret(s).

Grant Types

Because they use a trusted backend server, confidential applications can use grant types that require them to authenticate by specifying their client ID and client secret when calling the Token endpoint. They can use either the Post or the Basic Token endpoint authentication method.

These are considered confidential applications:

• A web application with a secure backend that uses the Authorization Code Flow, Resource Owner Password Flow, or Resource Owner Password Flow with realm support
• A machine-to-machine (M2M) application that uses the Client Credentials Flow

ID tokens

Because confidential applications can store secrets, you can grant them ID tokens that have been signed in one of two ways:

• Symmetrically, using their client secret (HS256)
• Asymmetrically, using a private key (RS256)

Public applications

Credentials cannot be securely stored in public applications.

Grant types

Only grant kinds that do not need the usage of the client secret can be used by public applications. They are unable to send a client secret because they are unable to keep the credentials required discreet.

These are public applications:

• A native desktop or mobile application that uses the Authorization Code Flow with PKCE
• A JavaScript-based client-side web application (such as a single-page app) that uses the Implicit Flow grant

ID tokens

Because public applications are unable to keep secrets, the ID tokens they get must be:

• Signed asymmetrically using a private key (RS256)
• Verified using the public key corresponding to the private key used to sign the token

Authorization Code Flow

Regular web apps can use the Authorization Code Flow, which exchanges an Authorization Code for a token, because they are server-side programs with no publicly accessible source code. Because you must pass along your application’s Client Secret, which must always be kept secure, and you will have to store it in your client during this exchange, your app must be server-side.

1. Within the usual online application, the user clicks Login.
2. SDK redirects the user to the Auth0 Authorization Server (/authorize endpoint) is redirected by the Auth0’s SDK..
3. The user is redirected to the login and authorisation prompt by your Auth0 Authorization Server.
4. After logging in with one of the configured login options, the user may be presented with a consent page detailing the permissions that Auth0 will grant to the standard web application.
5. Your Auth0 Authorisation Server sends the user back to the application with a one-time use authorization code .
6. Auth0’s SDK sends this code, along with the application’s Client ID and Client Secret, to the Auth0 Authorization Server (/oauth/token endpoint).
7. The code, Client ID, and Client Secret are all verified by your Auth0 Authorization Server.
8. An ID Token and an Access Token are returned by your Auth0 Authorization Server (and optionally, a Refresh Token).
9. The Access Token can be used by your application to call an API to get information about the user.
10. The API returns the info that was requested.

Resource owner password flow

1. The user clicks Login within the application and enters their credentials.
2. Your application forwards the user’s credentials to your Auth0 Authorization Server (/oauth/token endpoint).
3. Your Auth0 Authorization Server validates the credentials.
4. An Access Token is returned by your Auth0 Authorization Server (and optionally, a Refresh Token).
5. The Access Token can be used by your application to call an API to get information about the user.
6. The API returns the info that was requested.

Client Credentials Flow

1. Your app uses its Client ID and Client Secret to authenticate with the Auth0 Authorization Server (/oauth/token endpoint).
2. The Client ID and Client Secret are validated by your Auth0 Authorization Server.
3. An Access Token is returned by your Auth0 Authorization Server.
4. The Access Token allows your application to make API calls on its own behalf.
5. The API returns the info that was requested.

Authorization Code Flow with Proof Key for Code Exchange (PKCE)

Native apps

• A Client Secret cannot be stored in a secure manner. The Client Secret is connected to the program and is the same for all users and devices, therefore de-compiling it will reveal it.

Single-page apps

• Because the browser has access to the complete source, it is impossible to store a Client Secret safely.

Given these circumstances, OAuth 2.0 provides a Proof Key for Code Exchange version of the Authorization Code Flow (PKCE)

The PKCE-enhanced Authorization Code Flow introduces the Code Verifier, a secret created by the calling application that can be confirmed by the authorization server. In addition, the calling app generates a Code Verifier transform value called the Code Challenge and delivers it over HTTPS to get an Authorization Code. Without the Code Verifier, a malicious attacker can only intercept the Authorization Code and not exchange it for a token.

1. Within the program, the user clicks Login.
2. The Auth0 SDK generates a code_challenge from a cryptographically-random code_verifier.
3. With the code_challenge, the Auth0 SDK returns the user to the Auth0 Authorization Server (/authorize endpoint).
4. The user is redirected to the login and authorization prompt by your Auth0 Authorization Server.
5. After authenticating with one of the configured login options, the user may be directed to a consent page that lists the permissions that Auth0 will provide the application.
6. The code challenge is stored by your Auth0 Authorization Server, and the user is redirected back to the application with an authorization code that is only valid for one usage.
7. The Auth0 Authorization Server receives this code and the code verifier (generated in step 2) via the Auth0 SDK (/oauth/token endpoint).
8. The code_challenge and code_verifier are verified by your Auth0 Authorization Server.
9. An ID Token and an Access Token are returned by your Auth0 Authorization Server (and optionally, a Refresh Token).
10. The Access Token can be used by your application to call an API to get information about the user.
11. The API returns the info that was requested.
12. If Refresh Token Rotation is enabled, each request generates a new Refresh Token, which is issued along with the Access Token. When a Refresh Token is exchanged, the preceding Refresh Token is invalidated, but the authorization server retains information about the relationship.
13. If Refresh Token Rotation is enabled, each request generates a new Refresh Token, which is issued along with the Access Token. When a Refresh Token is exchanged, the preceding Refresh Token is invalidated, but the authorization server retains information about the relationship.

If you have Refresh Token Rotation enabled, a new Refresh Token is generated with each request and issued along with the Access Token. When a Refresh Token is exchanged, the previous Refresh Token is invalidated but information about the relationship is retained by the authorization server.

Implicit Flow

To achieve web sign-in for a typical web app, you can utilize OpenID Connect (OIDC) with a variety of flows. The authorization code flow done by the app backend is used to obtain an ID token in one common flow. This solution is efficient and reliable, but it necessitates the acquisition and management of a secret by your web app. If all you want to do is implement sign-in and don’t need access tokens for invoking APIs, you can skip this step.

Formal Flow with Implicit Flow Post flow implements web sign-in using OIDC, which is quite similar to how SAML and WS-Federation work. The front channel is used by the web app to request and get tokens, eliminating the need for secrets or additional backend calls. You won’t need to obtain, keep, use, or safeguard a secret in your application if you use this method.

1. In the app, the user selects Login.
2. The Auth0 SDK sends the user to the Auth0 Authorization Server (/authorize endpoint), with an id_token response type parameter indicating the type of credential sought. To enhance security, it also sends a response_mode parameter of form_post.
3. The user is redirected to the login and authorization prompt by your Auth0 Authorization Server.
4. After authenticating using one of the configured login options, the user may be directed to a consent screen detailing the permissions that Auth0 will provide the app.
5. With an ID Token, your Auth0 Authorization Server redirects the user back to the app.

References

[1] https://datatracker.ietf.org/doc/rfc6749/