Salesforce can participate in a number of standard OAuth 2.0 flows acting as either the client, or as the authorisation and resource server. The flows in this section are the common general flows which are used for either user or server authorisation and authentication - flows to be applied in specific circumstances can be found in the "Specialised OAuth 2.0 Flows" section.
The diagrams are shown
in general terms as Salesforce can play the role of client or server.
Considerations specific to Salesforce are mentioned in the notes.
- Based on the
OAuth Authorisation Code Grant flow
- Gold standard for security if
the client secret can be protected by the client application - generally
this is the case when the application is operating in a trusted
environment (e.g. an internal enterprise server application)
- Code challenge is optional and
used together with code verifier in the token request to provide
PKCE (proof of key exchange), which adds an additional layer of security.
More detail on this is explained in the notes for the Authorisation Code
with PKCE flow.
- For Salesforce to act as the
authorisation & resource server, a connected app controlling
configuration and access policies is needed
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_web_server_flow.h…
- The Salesforce User-Agent flow
is based on the OAuth 2.0 Implicit Grant flow
- Flow can be used in
circumstances where a client secret can't be protected, for example
in a mobile or desktop application, or client app running in a
browser, such as a SPA
- The flow is currently used
within the Salesforce Mobile SDK, so apps developed through this framework
(which includes Mobile Publisher apps) will typically authenticate to
Salesforce in this way
- Identity is based on the
same-origin policy (redirect_uri must match one of the Callback URL
values in connected app)
- The flow is sub-optimal from a
security perspective in many scenarios, as tokens are transmitted in URL.
This means they are accessible to the browser and stored in browser
history, which is frequently synced across devices and
susceptible to attack. It's advisable to ensure that access
token validity is short and refresh tokens aren't used to reduce the risk
of such attacks
- Prior to 2017, this flow was
recommended as best practice for mobile and native applications, however
the current recommendation is to implement the more secure Authorisation
Code with PKCE flow described below in contexts where an out of band POST
can be made
- For Salesforce to act as the
authorisation & resource server, a connected app is needed
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_user_agent_flow.h…
https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/oa…
- Since 2017, Authorisation Code
with PKCE has been recommended as the most secure flow for
mobile and native apps by the Internet Engineering Task Force (IETF). Their
white paper recommendation is linked below
- The major advantage it has over
implicit grant (User-Agent) is that although there's no need for
the client to protect credentials or a secret, tokens are
returned through a secured channel (an out of band HTTPS call) rather than
via the browser URL, which is open to malicious interception
- PKCE (Proof of Key Exchange)
refers to the use of "code verifier" and "code
challenge", which provide an additional layer of security. Code
verifier is a 128 byte base64url encoded random string generated by the
app, and code challenge is the base64url encoded SHA256 hash of this
string
- Native apps may make use of a
custom URL scheme (e.g. MyApp://) or localhost (e.g. http://localhost/) to
capture redirects, potentially allowing malicious applications to receive
an authorisation code
- However, the
authorisation server can be confident the application is making an
authorised token request by comparing code challenge to the hash of code
verifier. When these match, the authorisation server can be confident
the entity making the token request is the same one which requested the
authorisation code - the one-way nature of the hash function makes it
difficult for an attacker to find a matching code verifier and so impersonate
the authorised client even if code challenge and auth code are intercepted
- To configure Salesforce as an
authorisation server allowing this flow, a connected app is needed
with the option "Require Secret for Web Server Flow" disabled
Documentation
https://www.rfc-editor.org/rfc/rfc8252.txt
https://auth0.com/docs/flows/concepts/auth-code-pkce
Salesforce Web Server Flow documentation
(includes detail of code_challenge imp…
- JSON Web Token (JWT) is created
and signed with private key of an X509 certificate by client app
- Authorisation server checks
signature against public key of certificate to verify authenticity of
request
- Allowed scopes are based on
approval previously provided by the user through another OAuth flow
- For Salesforce to act as the
authorisation & resource server, a connected app is needed
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_jwt_flow.htm&type…
- SAML assertion is
created and signed with private key of an X509 certificate by
client app
- Authorisation server checks
signature against public key of certificate to verify authenticity of
request
- Allowed scopes are based on
approval previously provided by the user through another OAuth flow
- For Salesforce to act as the
authorisation & resource server, a connected app is needed
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_SAML_bearer_flow…
- Needs to be complete trust
between applications for this to be appropriate
- Even with complete trust there
are more secure alternatives for most use cases (e.g. web server for user
authentication or JWT bearer for server authentication)
- An example use case would
be a user entering a password in real time on an internally
managed client application which doesn't support a browser-based
identity flow
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_username_password…
- Used to exchange a refresh
token for an access token when required
- An app will need to invoke this
flow each time an access token expires. Access token expiry can be
identified by a status code 401 ("Unauthorized") or sometimes
403 ("Forbidden") error response from a resource
server endpoint. If Salesforce is the resource server, this
response will be 401 with error
code "INVALID_SESSION_ID"
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_refresh_token_flo…
- Enables authorisation
of devices with limited input capabilities
- Device code is valid for 10
mins after being generated
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_device_flow.htm&t…
- 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 in 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
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_asset_token_flow…
- Assertion must be signed by the
private key of the IDP certificate
- Recipient & audience (if
restricted) within the SAML assertion must be the Salesforce org
login URL, meaning any SAML request requested from an IDP by the
client cannot be re-used, since the EntityID in the audience will be
the client app rather than Salesforce
- The restrictions above make
this flow impractical to use for many circumstances. One possible
application would be when the client app is able to generate a SAML
request and has access to the IDP's private key to sign the assertion
- A key difference between this
and other OAuth 2.0 flows used for Salesforce is that this doesn't require
a connected app. Instead single sign on must be enabled with configuration
matching the entity ID and certificate of the identity provider
Documentation
https://help.salesforce.com/articleView?id=remoteaccess_oauth_web_sso_flow.htm&…
CANVAS APP
SIGNED REQUEST FLOW
- This flows is offered as an
alternative to the canvas app initiating a standard OAuth flow (e.g.
user-agent)
- The advantage of the signed
request flow 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 POST request. 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
OAUTH 2.0 LOGIN AND CONSENT
A number of the
OAuth 2.0 flows (OIDC Connect, Web Server, User-Agent, Device Authorisation
etc) rely on authentication (login) and authorisation (consent to
requested scopes) being handled in an interaction between the client app
and the authorisation server.
In the diagrams in
other sections, this is shown as a simplified "Authentication and
Consent" step or similar. The diagram below shows in a bit more detail the
steps involved in a typical interaction where both authentication and consent
are needed.
Note that there are
variations of this flow - e.g. in OAuth with SAML, authentication to the
authorisation server is handled through SAML.
If Salesforce is acting as the authorisation server, relevant endpoints
are:
- Authorisation endpoint: <mydomainname>.my.salesforce.com/services/oauth2/authorize
- Login
page: <mydomainname>.my.salesforce.com
- Authorisation page: <mydomainname>.my.salesforce.com/_ui/identity/oauth/ui/AuthorizationPage
- Token endpoint: <mydomainname>.my.salesforce.com/services/oauth2/token
SALESFORCE LAYERED FLOWS
This section outlines
some common ways that OAuth flows are used in combination with single sign on
to facilitate authentication and token exchange without prompting for direct
login to the authorisation server.
The notes and labels
concentrate on the interactions between the flows - for more details on
features of each flow check the diagrams in the relevant section
OAUTH 2.0 WEB
SERVER WITH SAML
- My domain is required, as the
authentication part is an application of the SP-initiated SAML flow
OAUTH 2.0
USER-AGENT WITH SAML
- As above, my domain is required
to support this flow
OAUTH 2.0
USER-AGENT WITH SOCIAL SIGN ON
- Flow would typically be used by
a native or hybrid mobile app allowing social registration / sign on
- Used by MobileSDK
SALESFORCE SINGLE SIGN ON FLOWS
Single Sign On
(SSO) flows enable users to authenticate using their identity from an
external system. There are three mechanisms which can be used to achieve this
in Salesforce:
- SAML, where signed structured messages known as SAML
requests and assertions are passed between the identity
provider and service provider via the browser.
- OpenID Connect, which leverages OAuth web server or user agent
flows to establish trust.
- Delegated Authentication, a mechanism based on capturing and submitting
credentials for authentication via a SOAP message. Can be useful for
authenticating to systems which don't offer other protocols.
Flows in this section
summarise the sequence of messages in SSO approaches currently supported
by Salesforce.
IDENTITY
PROVIDER (IDP) INITIATED SSO
If Salesforce
acts as the Service Provider:
- Salesforce configuration is
done through Setup -> Single Sign On settings
- My domain isn't required
- Authorisation Consumer Service
(ACS) URL to provide to the IDP is the "Salesforce Login URL"
- Certificate from the IDP should
be uploaded as the identity provider certificate in Salesforce. This is
used for signature validation
- Requests will be signed by
Salesforce with the selected certificate, which can be validated
by the IDP if necessary
- IDP-encrypted assertions are
also supported, and decryption certificate uploaded and selected
as Assertion Decryption Certificate
Salesforce as an
IDP doesn't use this flow. Instead an SP-initiated version
with Relay_State = Start URL will be used to access an SP application from
Salesforce
Documentation
https://help.salesforce.com/articleView?id=identity_provider_about.htm&type=5
SERVICE PROVIDER
(SP) INITIATED SSO
If Salesforce acts as
the Service Provider:
- MyDomain required for this
flow, which enables deep linking (landing on requested URL) and
OAuth with SAML
If Salesforce acts as
the Identity Provider:
- Configure in
Salesforce through Setup -> Identity Provider
- A connected app must be set
up for each service provider, specifying the Authorisation Consumer
Service (ACS) URL to be used to determine where the SAML
response is sent
- User profiles or permission
sets must be added to connected app for accounts to be used for SSO
identity
- Relay State is set to the
app's Start URL if the app's icon is clicked in the Salesforce
app launcher
Documentation
https://help.salesforce.com/articleView?id=identity_provider_about.htm&type=5
- Flow is used in Social-Sign On
(in which case Salesforce is the Relying Party)
- Client id and secret in
Social-Sign On are managed by Salesforce for supported providers
(Facebook, Google etc) unless specified otherwise
- The flow is also used for
authentication to content providers (e.g. Google or Office 365) for
Salesforce Files Connect
- This flow, or the User Agent
equivalent, can also be used when Salesforce is the OIDC Provider
- The UserInfo endpoint can
be used to provide ID claims not included in the scope of
the ID token, for example picture, email, website, locale, phone
number etc
- The OpenID Connect Core spec includes details on implementation of this flow
Documentation
https://developer.salesforce.com/docs/atlas.en-us.externalidentityImplGuide.met…
https://openid.net/specs/openid-connect-core-1_0.html
DELEGATED
AUTHENTICATION FROM SALESFORCE LOGIN
- Provides a method of using
credentials for applications which don't offer SAML to login to
Salesforce
- My domain is not required
- Delegated authentication SOAP
endpoint must comply to specific WSDL (which can be downloaded from
Salesforce)
- Password is not validated in SF
and instead passed to authentication service for validation, so
Salesforce password policy doesn't apply
- This flow requires delegated
authentication endpoint to support processing passwords
- Delegated authentication can be
enabled / disabled by an admin from Single Sign On Settings
- Permission "Is Single
Sign-On Enabled" controls by user whether passwords are submitted to
delegated authentication service
SAML
migration trick: It can be useful
to block certain users from logging in with username and password. By
enabling delegated authentication and using the "Is Single Sign-On
Enabled" permission, these users will be prevented from using their
Salesforce password to login
Documentation
https://help.salesforce.com/articleView?id=sso_delauthentication_configuring.ht…
DELEGATED
AUTHENTICATION (HTTP)
- Enables authentication to
Salesforce without prompting for credentials
- Application must manage or be
able to acquire the token, assertion or password
- A token or assertion is
preferable to avoid sending corporate passwords to or from Salesforce
- If a token or assertion is
used, this should be set as the password in the POST to the Salesforce
login page
Documentation
https://help.salesforce.com/articleView?id=sso_delauthentication_configuring.ht…
Comments
Post a Comment