Salesforce OAuth Flow - Implementation guidelines and tips

Whenever an external app request to access salesforce data, authentication needs to be done on salesforce side. Different authentication flows are available as governed by OAuth standards.

Through this blog, i will share commonly used OAuth flows and factors which you need to consider while deciding which one to use.

OAuth 2.0 Web Server Authentication Flow

• This flow is mainly used by applications hosted on web server.
• If external application is trusted one and hosted on secure server and can securely store client_secret, then flow can be used.
• This flow is used mainly to build web application.
• First of all external application will request for access_token and user will be redirected to login page for authentication. After authentication, user will approve salesforce access by external app.
• After successful approval to grant access, authentication code will be returned through callback. External app will utilize this temporary OAuth token( valid for 10 mins) and send POST request to get access_token by sending temporary OAuth code, client_id and client_secret.
• Salesforce will return access_token and refresh_token. Refresh token can be used to regenerate the access token by external app so that user is not required to authenticate every time.
• Instead of sending client credentials as parameters in the body of the access token POST, Salesforce supports the HTTP Basic authentication scheme. This scheme's format requires the client_id and client_secret in the authentication header of the post as follows:         Authorization: Basic64Encode(client_id:secret)
• This flow is not recommended for application (like ETL or middleware's) which will access salesforce using API's and no UI is involved.

OAuth 2.0 User Agent Flow

• This flow is recommended when you build mobile or desktop application and your application can be distributed to anyone. So these kind of application are not considered as safe to store client secret because source code of application will be accessible to everyone and client secret can be exposed easily.
• This flow is used when external system application wants to login into salesforce using salesforce login credentials. Once user logged in, then he/she to approve that external application can fetch salesforce data(scope defined in connected app).
• In this flow, external application will pass only client id and user login page opens and user authenticate themselves to get access token, refresh tokens.
• External application can use use refresh token to get new access token if it get expired and can avoid logging user again in salesforce.
• With the user-agent authentication flow, the client app receives the access token as an HTTP redirection. The client app requests the authorization server to redirect the user-agent to another web server or to an accessible local resource. The server can extract the access token from the response and pass it to the client app. For security, the token response is provided as a hash (#) fragment on the URL. It prevents the token from being passed to the server or to any other servers in referral headers.

OAuth 2.0 JWT Bearer Token Flow

• Ideal for application which access sfdc only through API as there is no UI involved. For example ETL tools or middleware.
• A JSON Web Token (JWT) enables identity and security information to be shared across security domains. 
• JWT is basically a JSON file consisting of a header and claims object, where the header contains the signature algorithm and the claims object contains specific information such as the username and consumer key. At a high level, you will then sign the JSON object with the private key of your certificate and send the JWT to Salesforce to obtain an access token.
• When a client wants to use this flow, posts an access token request that includes a JWT to Salesforce’s OAuth token endpoint. Salesforce authenticates the authorized app through a digital signature that is applied to the JWT. 
• Digital certificates are required in this flow. Upload certificate (X509 ) to connected app which will be used to authenticate JSON web tokens.
• External application send request for access token by passing JWT token in body. SFDC server validate JWT and return access token to external app.
• No refresh token is returned in this flow. So if access token expires then send request to generate access token again.

OAuth 2.0 SAML Bearer Assertion Flow

• A SAML assertion is an XML security token issued by an identity provider and consumed by a service provider.
• The external app or client isn’t required to store client_secret.
• If you use active directory or LDAP as identity provider, then you will use SAML assertion from your SSO flow to obtain an access token to Salesforce.
• This flow used SAML assertion (XML token generated by Identity provide) and applied digital signature to it using certificates.
• In connected app, you upload this certificate (X509 ) containing private key. This key should be used while signing SAML asseration(base 64 encoded).
• The SAML assertion is posted to the OAuth token endpoint, which in turn processes the assertion and issues an access_token based on prior approval of the app(users are pre- authorized in connected app). 
• This flow also return only access token not refresh token

SAML Assertion Flow

• The SAML assertion flow is an alternative for Orgs that are currently using SAML to access Salesforce and want to access the web services API the same way. 
• You can use the SAML assertion flow only inside a single org.  So it means it can be used to connect to single sfdc org
• You don’t have to create a connected app to use this assertion flow. Clients can use this assertion flow to federate with the API using a SAML assertion, the same way they federate with Salesforce for web single sign-on.
• If you have SSO configured specifically for the Salesforce org that your partner application is authenticating to, you can also use the SAML Assertion Flow. 
• Configure SAML for your org. SAML version 2.0 is required. Exchange a SAML assertion for an access token. Use a JSON parser to process the response from salesforce to extract the access_token.
• The benefit of this flow is that you can use a Base-64 encoded, then URL encoded, SAML assertion that is normally used for web single sign-on. This makes it significantly more simple from a development perspective because you don't need to create a connected app but requires you to have SSO enabled for your Salesforce instance.
• No refresh token is issued in this flow.

OAuth 2.0 Username and Password Flow

• Use the username-password authentication flow to authenticate when the consumer already has the user’s credentials.
• Avoid using this flow because you have to send username and password un-encrypted to Salesforce.
• Use this flow only when there is no way to connect by using other available flows.
• Salesforce communities don’t support the OAuth 2.0 username-password authentication flow.
• In this flow, external app or client sends client_id,client_secret, username and password in POST request.
• The security token must be added to the end of the password to log in to Salesforce from an un-trusted network. Concatenate the password and token when passing the request for authentication.
• No refresh token is issued.

OAuth 2.0 Device Authentication Flow

• The OAuth 2.0 device authentication flow is typically used by applications on devices with limited input or display capabilities, such as TVs, appliances, or command-line applications. 
• This flow returns access_token and refresh_token.
• When device requests authorization by specifying client_id, Salesforce verifies the request and returns the following: human-readable user code, verification URL, device code, and minimum polling interval (in seconds).
• User navigate to verification URL and enters user code received.
• User prompted to login and approve access to salesforce data.
• In the meantime, the application running on the device should keep polling Salesforce (polling interval is also returned by Salesforce) and once the user has approved access, the application on the device will get an access token issued.
• After the access token is granted, the device can use it in API requests to access data on the user’s behalf. The device uses a refresh token to get a new access token if the access token becomes invalid.

OAuth 2.0 Asset Token Flow

• Client applications use the OAuth 2.0 asset token flow to request an asset token from Salesforce for connected devices. 
• In this flow, the device obtain an access token (in any of the above ways) and use this token alongside additional information to create an actor token. This token contains valuable information about the asset which is then send to Salesforce where it is exchanged for an asset token. Subsequent requests to protected resources at Salesforce can then be made with the asset token.
• In this flow, an OAuth access token and an actor token are exchanged for an asset token. This flow combines asset token issuance and asset registration for efficient token exchange and automatic linking of devices to Service Cloud Asset data.

OAuth 2.0 Refresh Token Flow

• The OAuth 2.0 refresh token flow renews tokens issued by the web server or user-agent flows.

Revoking Tokens

• Revoke an OAuth token if you don’t want the client app to access Salesforce data or if you don’t trust the client app to discontinue access on its own.
• When users request their data from within an external app (the consumer’s page), they’re authenticated. You can revoke their access tokens, or the refresh token and all related access tokens, using revocation. Developers can revoke the token when configuring a log-out button in their app.
• You can use POST method to revoke token as mentioned below

To revoke OAuth 2.0 tokens, use the revocation endpoint.
https://login.salesforce.com/services/oauth2/revoke 
Construct a POST request that includes the following parameters using the application/x-www-form-urlencoded format in the HTTP request entity-body. For example:
    POST /revoke HTTP/1.1
    Host: https://login.salesforce.com/services/oauth2/revoke 
    Content-Type: application/x-www-form-urlencoded
    token=currenttoken

• Salesforce also supports GET requests with the query string parameter token and the current token. If an access token is included, Salesforce invalidates it and revokes the token. If a refresh token is included, Salesforce revokes it and any associated access tokens. For example: 

https://login.salesforce.com/services/oauth2/revoke?token=currenttokenID

The authorization server indicates successful processing of the request by returning an HTTP status code 200. For all error conditions, status code 400 is used.

• If an access token is included, Salesforce invalidates it and revokes the token. If a refresh token is included, Salesforce revokes it and any associated access tokens.

You can also navigate to "Connected Apps OAuth Usage" under set up and block external app to create new sessions with connected app.

Hope this will help!!!