OAuth

Owned by Jodie Miners
Last updated: Oct 19, 2020
4 min read

Open standard for Authorisation. Used as the main standard for authentication for APIs integrating two or more systems.

Access can be between

  • User and Service

  • Two services

  • For a given scope

Connected Apps

  • By default, when a user accesses another application via OAuth a connected app is created automatically???

  • If you have whitelisting enabled (contact Salesforce to enable) you must specify which apps can be connected. This should be set up wherever possible so users don't use dataloader or workbench without knowing what they are doing.

  • However there is nothing to prevent users from using username / password / token authentication (eg Enabler4Excel has both options and is free to use to download data to Excel).

  • OAuth connections can be revoked by the Admin, or at the user level via user settings > connections

Flows

  • Username Password Flow

  • Web Server Flow

User Agent Flow

  • The most used flow with Salesforce. Where a user logs in. Eg via a mobile app, or a third party app like Workbench

  • Steps

    • Go to Workbench and login

    • Workbench redirects you to the Salesforce login screen

    • You log in to Salesforce

    • You are prompted to approve sharing data you have access to in Salesforce to Workbench via the scopes. Be aware of the scopes that are requested

    • Workbench receives a callback from Salesforce with the access token. The callback includes

      • access_token - the Salesforce session id

      • Identity URL - id - user details. Basically the URL of the user record

      • issued_at - date and time the access token was issued (unix time)

      • token_type - eg bearer

      • instance_url - your Salesforce instance URL

      • signature - client secret key, encoded

      • scope - eg id+api+refresh_token

      • state -

JWT Flow

SAML Bearer Assertion Flow

  • Enables applications to reuse an existing authorisation by supplying a SAML assertion

  • I don't know when it would be used but it seems older than JWT but similar in that it doesn't require the user to intervene.

  • Is an XML security token issued by an identity provider (another app) and consumed by a service provider (Salesforce)

  • External app is already authorised. The user is previously authorised. (eg by being allowed to use this connected app).

  • The user needs to click allow

  • Can only be used after the consumer has received a refresh token from the authorisation

  • Need to to set a long expiry for the session timeout

  • The user is authorising this connected app to get the token it needs to do its thing.

  • Authentication by digital signature (certificate)

  • Matched to the certificate stored against the Connected App in Salesforce. X.509 certificate.

  • Not required to store the refresh token. Refresh token never issued.

  • Client secret not required (because we have the certificate)

  • It's similar to a refresh token

  • Steps

    • Create the connected app

    • It needs the refresh token scope

    • Upload the certificate. This is the public key for the app.

    • The client id is created by the connected app.

    • Client app generates SAML assertion and signs it with their private key.

    • Hit the token endpoint POST and send the SAML assertion to that endpoint

      • Issuer - client_id of the connected app

      • Audience - login.salesforce.com

      • Recipient (the /oauth2/token endpoint)

      • Subject - Salesforce User Name. (SAML configuration in the connected app)

      • SAML Assertion Base64 encoded and signed using RSA and SHA-1 or SHA-256

        • Grant_type:saml2-bearer

  • Token endpoint validates the certificate and the audience, issuer and subject. These are parameters on the endpoint.

    • Salesforce issues acess token (session id)

    • Token type bearer

  • Scope can't be specified in the assertion because it's set uo on the connected app

Roles

  • Resource Owner - the user accessing the service. (yep this one sounds wrong)

    • Accesses the application

    • Authenticates against the authorisation server

  • Client - the application / service that is being accessed.

    • Accesses data from the resource server after an Access Token is issued from the authorisation server. Lasts the length of the session.

    • Two types of Clients - Secure and Public

    • Consumer Key is used to identify itself to the Resource Server

    • Refresh token is used to request a new Access Token

  • Resource Server - the server that hosts the application

    • Provides data to the application

    • Delegates to the the authorisation server to issue the token

  • Authorisation Server - usually the resource server, but can be separate.

    • Accepts the request from the resource owner to authenticate

    • Issues the token so the user can access the application

Grant Types

  • Authorisation code

  • Implicit - access token sent directly to the client. Not recommended for use.

  • Resource owner password credentials - username and password sent. Not recommended for use except where security is not really needed

  • Client Credentials - used for server to server

  • Device Code - eg for logging in via your TV

Scopes

Examples in Salesforce are

  • api - eg REST or bulk API access

  • full (don't just cop out and use this one because it's easy) - full access to all the data that the Salesforce user can usually see.

  • Id - user identity. It comes as part of every other Salesforce scope.

  • openid

  • refresh_token - no other scopes included. Without refresh token you will be authorised initially but you will have to log in every time

  • visualforce - if the client should only access visualforce pages (and the data they use)

  • Web

  • Custom_permission - you can create your own scope and control access via code

  • Chatter_api - only access to chatter via the API