Device Authorisation Flow
- Enables authorisation of devices with limited input capabilities
- Device code is valid for 10 mins after being generated
Reference Implementations
Specialised OAuth 2.0 Flows
The Salesforce identity flows in this section are intended to be applied in the specific circumstances described in the notes, and provide capabilities and functionality specific to these contexts. Flows to be used for common authentication use cases can be found in the "General OAuth 2.0 Flows" section.
Asset Token Flow
- Actor token is a signed JWT including information about device (e.g. name, serial number, contact or account to link to in Salesforce)
- Device uses asset token to authenticate to a backend service
- Proof of key possession can be used to provide additional security for API calls - this can be implemented by signing the actor token with the device private key, and binding device public key to asset token in later API requests
- Asset token can be exchanged for an OAuth access token issued by the device backend for more efficient exchange if multiple calls are required
- AssetTokenEvent subscription includes information from the actor token and can be useful for initiating processes from actor token registration, for example automatically raising a case
Canvas App Signed Request
- Signed request flow is offered as an alternative to the canvas app initiating a standard OAuth flow (e.g. user-agent)
- The advantage over a standard OAuth flow is that a user can log in to the canvas app without needing to consent to sharing scopes, and without the app needing to store and manage a token
- The Canvas SDK features an implementation of this method which can be used by third party apps
- The signed request is appended as parameter in the final POST request shown to the canvas. The request consists of a hashed, signed base64 encoded context, and the base64 encoded context itself separated with a period
- repost() and refreshSignedRequest() Canvas SDK methods allow either the client or server (respectively) to issue or request new tokens on demand, and can be useful after redirects within canvas app, or after OAuth token expiry. The browser-based repost() method is shown in this flow
- The flow in the optional section here assumes the user is permitted access to the app but doesn't yet have a valid approval. Behaviours in other scenarios are described in the table
Hybrid App Token Flow
- Session IDs (SID) are returned with the access token for each requested domain scope (lightning, visualforce and content) to allow the app to directly bridge a session by setting SID values in cookie(s) for the relevant domains
- Session tokens are bound to the access token, so processes to manage renewing tokens can be aligned
- Without this flow, bridging a web session would require a POST to the frontdoor.jsp URL with the access token, which would redirect and set a SID cookie for the requested resource. Under this approach, access tokens and web sessions can expire independently so management is a little more challenging
- Both user agent and web server versions of the flow are possible (user agent is pictured)
- A corresponding refresh token flow (
grant_type=hybrid_refresh) is available for renewing tokens - Developed to support Mobile SDK 9.1, and hybrid_token grant type is now used in the core Mobile SDK project
SAML Assertion Flow
- This flow makes use of a Single Sign On (SSO) configuration in Salesforce for authentication rather than a connected app, which isn't required.
- In general, as part of an SSO configuration Salesforce will accept SAML assertions which:
- Are signed by the Identity Provider (IDP)
- Have the Recipient attribute in the SubjectConfirmationData element set to an org-specific Login URL or OAuth 2.0 Token Endpoint indicated on the SSO settings page
- Have an AudienceRestriction element with an Audience element indicating the correct Salesforce Entity ID
- The restrictions above make this flow impractical for most circumstances, and either a JWT or SAML bearer flow would almost always be preferable for server-server integrations.
- Historically, the SAML Assertion flow has been used in the context that a client app authenticated by an IDP needs to then authenticate as the logged in user to Salesforce. In some circumstances the SAML assertion could be reused by the client app to directly authenticate to the Salesforce org in this way. For this to be possible, the assertion can be created by the IDP with multiple AudienceRestriction elements, however Salesforce appears to only support the presence of a single SubjectConfirmationData element, which must have a Salesforce login URL as Recipient, so suitability would depend on the implementation of SAML in the client application.
Reference Implementations