These are my OAuth authorization flow notes for my Identity and Access Management Certification Study. They cover the parts that I wanted to dive into, so please keep the source documentation as your go-to place, and use these as a summary/aid to support any research you are doing.
What is OAuth 2.0 Authorization flows?
OAuth 2.0 is used for securing access to APIs. To use OAuth 2.0 in systems, one of several authorization flows is used. At a high level, the OAuth 2.0 authorization flows grant restricted access to a resource server’s protected resources to a client application. The authorization flows involve the passing of tokens in order to access a resource.
“The OAuth 2.0 authorization framework is a protocol that allows a user to grant a third-party website or application access to the user’s protected resources, without necessarily revealing their long-term credentials or even their identity.”
From AuthO: https://auth0.com/docs/authenticate/protocols/oauth
The OAuth 2.0 authorization flows are used for authorization and not authentication.
Each authorization flow has actors that have specific roles in the overall OAuth 2.0 solution.
Let’s break down the actors that can be found in all OAuth 2.0 authorization flows:
- Client Application:
Usually a cloud or mobile application, the client requests access to resources controlled by the resource owner and hosted by the resource server and is issued a different set of credentials than those of the resource owner. - OAuth 2.0 provider:
The OAuth 2.0 authorization server. The Authorization server authorizes the client, and gives out access tokens to the Client. - Resource Server:
Hosts the protected resources that the Client seeks to access. The REST API which protects the resource. - Resource Owner:
User or User Agent who owns the protected resource. This could potentially be the person who is using the client to access their own protected resource.
The steps that are common to all OAuth 2.0 authorization flows are:
- Client requests access to a protected resource
- Authorization server grants access tokens to the Client
- Resource server validates the access tokens
- Resource server approves access to the protected resource.
Typical OAuth 2.0 authorization flows used with Salesforce are below. The first three listed here require user interaction:
- Authorisation Code and Secret (Web Server)
The web server flow is used for web app integration. With this flow, the server hosting the web app must be able to protect the connected app’s identity (the client ID and client secret).
For this flow, the client application redirects the end user’s browser to the Salesforce login page (the authorization endpoint). The user logs in (authenticates themselves) and approves the client application to access. The client application does not acquire the user’s login credentials.
Salesforce (in this instance the authorization server) sends an authorization code to the client application to the callback URL.
The client application uses this code to request an access token from Salesforce.
Salesforce exchanges the authorization code for the access token (a session id that can only be used against the REST API being used and not in the UI), the token type, and a refresh token (which is why the web server must be securely protected). The client application then uses the access token to access protected resources on REST API endpoints. - Implicit Grant (User – Agent)
The implicit grant type otherwise known as the User Agent flow is used to obtain access tokens – but does not support the issuing of refresh tokens.
It is a redirection-based flow. The client application interacts with the resource owner’s user-agent (such as a web browser) and must be capable of receiving incoming requests in the form of a redirection from the authorization server.
There is no authentication included with this flow so the resource owner has to be present.
This is generally used to enable users to authorize a desktop or mobile app to access data using an external or embedded browser. The token response is provided as a hashtag (#) fragment on the URL.
So with the user-agent flow, the connected app for the client app needs to receive the access token as an HTTP redirection to a web server or accessible local resource. - Authorisation code and PKCE
This is an OpenID connect flow designed to authenticate native or mobile application users. See my notes on this here. It is a particularly useful flow for clients that cannot protect a global secret and therefore better than Implicit Grant / User-agent flow.
These do not require user interaction:
- JWT Bearer flow
This is for server-to-server integrations. The flow uses a certificate to sign the JSON Web Token (JWT) request and does not require user interaction to run – however, it does require prior approval of the client app.
The client posts a JSON web token to the Salesforce OAuth endpoint. Salesforce then processes it. The JST includes a digital signature. Salesforce issues an access token based on the prior approval of the app.
Prior approval happens in one of two ways via the connected app policies:
1) Admin-approved users are pre-authorized: permissions sets and profiles can be used to provide prior approval.
2) All users may self-authorize: An end-user approval and issuing of a refresh token can be used with this – however, the client does not need to pass a client secret to the token endpoint.
The JWT must be signed using RSA SHA256. This uses an X509 certificate as the signing secret. - SAML Bearer Assertion Flow
A client, via a connected app, uses a previous authorization to request an OAuth access token. The previous authorization is in the form of a signed SAML 2.0 assertion. The SAML assertion has a digital signature applied and this authenticates the authorized app. The SAML assertion is an XML security token from an identity provider. This is consumed by the service provider. - Username-Password
Used with Salesforce Mobile SDK and Mobile Publisher. In the Mobile app, the tokens are stored in a URL hash fragment instead of a query string parameter and Sessions IDs are returned for re-authentication without having to rely on 3rd party cookies.
A note about Grant Access Tokens for JWT bearer and SAML assertion bearer flows from Salesforce Help:
“The OAuth 2.0 JWT bearer and SAML assertion bearer flow requests look at all previous approvals for the user that include a refresh token. If Salesforce finds matching approvals, it combines the values of the approved scopes. Salesforce then issues an access token. If Salesforce doesn’t find previous approvals that included a refresh token or any available approved scopes, the request fails as unauthorized.
After a successful verification, the Salesforce instance sends a response to the connected app. A token response for the OAuth 2.0 JWT bearer token flow follows the same format as an authorization code flow, although a refresh token is never issued.”
Salesforce Help
Connected Apps and OAuth
All the above OAuth authorization flows need a Connected App set up, except for the SAML Assertion flow. To see how to set up a Connected App go to this article.
Using the connected app framework, external client applications are enabled to integrate with Salesforce using APIs and standard authentication protocols such as OAuth, SAML, and OpenID Connect.
Good resources to help with further study on this subject:
Salesforce (Both the documentation and the developer websites)
Cloud Sundial – Lawrence Newcombe’s website.
Further Hello Kloud articles on this subject:
- (see this article OAuth 2.0 User Agent Flow (and Authorisation Code Flow with PKCE))