Grant Types

  • Authorization Code Grant
    • Used to obtain both access tokens and refresh tokens
    • optimized for confidential clients
    • It is redirection-based
    • client must be capable of interacting with the resource owner’s user-agent and capable of receiving incoming requests.
  • Implicit Grant
    • used to obtain access token
    • Optimized for public clients
    • Clients are implemented in a browser using a scripting language like JavaScript.
    • redirection-based flow
    • clients must be capable of interacting with resource owner’s user-agent and capable of receiving incoming requests.
    • Client receives access token as a result of the authorization request.
    • The implicit grant type does not include client authentication, and relies on the presence of the resource owner and the registration of the redirection URI. Because the access token is encoded into the redirection URI, it may be exposed to the resource owner and other applications residing on the same device.

Scopes

  • Scope Parameter Values
    • api – allows access to current logged in user’s account using APIs such as REST and Bulk including chatter api
    • chatter_api – Allows access to Chatter REST API resources only
    • custom_permissions – Allows access to custom permissions that are associated with the connected app and shows whether current user has each permission enabled.
    • full – allows access to all data accessible by logged in user and encompasses all other scopes. Does not return a refresh token.
    • id – allows access to identity URL service. Can be used to request profile, email, address, or phone.
    • openid – allows access to the current logged in user’s unique identifier for OpenID connect apps. Use the openid scope in the OAuth 2.0 user-agent flow and the OAuth 2.0 web server authentication flow to receive a signed ID token conforming to the OpenID Connect specifications in addition to the access token.
    • refresh_token – allows a refresh_token to be returned when eligible to receive one.
    • visualforce – Allows access to customer created Visualforce pages. Does not allow access to standard Salesforce UIs
    • web – Allows the ability to use the access_token on the web and includes visualforce access.
    • custom scopes
      • To define a connected app’s permissions to access protected resources hosted by an external entity, OAuth custom scopes can be created.
      • The custom scope tells the external entity which information the connected app is authorized to access.
      • For example, you want to create a custom web app that can access customer order status data in your order status API. In Salesforce, you create an order_status OAuth custom scope. You assign the Salesforce custom scope to the connected app requesting access to the order status API. You then define an order_status policy in your external entity. This policy allows access to customer order status data in your order system’s API. When the external entity receives the connected app’s request to access a customer’s order status, it validates the connected app’s access token and order_status scope. With a successful validation, the app can access the customer order status information in the order system API.
  • All scopes include id which can be used to access Identity URLs

Tokens

  • Authorization Code
    • Are a type of OAuth token that authorize access for a very short amount of time
    • Are generated by Salesforce authorization server and passed to the client app via the browser
    • Are passed from the client App to the Authorization Server in exchange for an access / refresh token
  • Initial Access Token
    • Initial access token can be generated from connected app after configuring it.
    • Salesforce requires this to authenticate dynamic client registration request.
    • Regeneration of this token invalidates previous one that your OAuth clients use. Update OAuth clients (like Mulesoft) to use the new token.
  • Access Token
    • Are a type of OAuth token, known as the Session ID
    • Are used to make authenticated requests FOR the user
    • Have a longer lifetime than authorization codes usually in minutes to hours.
    • Must be protected from interception (via Transport Layer Security: TLS)
    • When an access token expires attempts to use it fail and app needs to obtain a new access token.
    • To use, set a SID cookie or use frontdoor URL including “web” in requested scopes.
  • Refresh Token
    • Can have an indefinite lifetime and can persist for an admin-configured interval or till revoked.
    • Can be stored within a client app
    • Can be used repeatedly to gain access, like a password
    • Can expire or be revoked, so the client app has to be able to handle failures
  • ID Token
    • an authentication layer on top of OAuth 2.0.
    • Are encoded as a JSON web token
    • Are signed data structures
    • Contain user ID, time issued and client ID

Token Expiration

  • Sessions expire based on your organization’s policy for sessions. Basically, as long as the app is in active use, the session won’t expire. Once the session is logged out, the timeout has elapsed, or it is otherwise expired (e.g. an administrator expires all sessions for the Connected App).
  • There’s no way to know how long it will be until your session expires. It’s not exactly “trial and error,” it is simply a normal process. Even if you were told that your session expired in two hours, it might not last two hours if an administrator revokes the session, the session remains in use.
  • If you use refresh tokens, your code should first try the regular API call, and if you get a 4xx result, try using the refresh token to get a new session token, and if that fails, then you’ve been kicked out, and the user needs to re-authenticate to continue. If you don’t use refresh tokens, you can skip the middle step, obviously.
  • OpenID Connect token introspection enables OAuth 2.0 connected client apps to check the current state of an OAuth 2.0 access or refresh token. An OAuth client that registers child OAuth 2.0 connected apps through the dynamic client registration endpoint can check the current state of access and refresh tokens for itself and its child apps
    • Endpoint: https://hostname/services/oauth2/introspect
    • Salesforce verifies the client credentials in the header and sends a response indicating whether the token is active. This response indicates that the token is still active.

Token Revocation

  • 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.
  • using revocation access tokens, refresh tokens and all related access tokens can be revoked.
  • Developers can revoke the token when configuring log out.
  • End Point: https://login.salesforce.com/services/oauth2/revoke
  • parameters: content-type: application/x-www-form-urlencoded, token (can be access or refresh token)
  • if access token is included, Salesforce invalidates it and revokes the token, if refresh token is included, Salesforce revokes it and any associated access tokens.
  • Salesforce also supports GET requests with query string parameter token and current token to revoke tokens.
  • https://login.salesforce.com/services/oauth2/revoke?token=currenttokenID
  • Revocation endpoint also accepts GET requests with an additional call back parameter and returns the response with content type application/javascript
  • https://login.salesforce.com/services/oauth2/revoke?token=XXXXX&callback=myCallback

References

3 Comments

  • Marvin Murphy Reply

    Oh my goodness! An amazing article.

  • Yee Waldo Reply

    Great website. Lots of helpful info here. I’m sending it to a few of my friends. thanks for your hard work!

  • Forest Reager Reply

    First time visiting your website, I enjoy your site!

Leave a Reply to Marvin Murphy Cancel reply

Your email address will not be published. Required fields are marked *