Given a scenario, determine the most appropriate flow type to recommend when implementing an OAuth solution where Salesforce is providing identity to a third party (for example, User Agent, Web Server, JWT, etc.)

/  No Comments

Authentication Flows

Web Server Authentication Flow

  • are for apps hosted on a secure server
  • must be used when the server must protect the secret
  • uses the “Authorisation Code” grant type, which is optimised for confidential clients and may request both access and refresh tokens
  • Steps
    • The web server redirects the user to Salesforce to authenticate and authorize the server to access the data on the user’s behalf.
      • End point: https://login.salesforce.com/services/oauth2/authorize
      • Required parameters: response_type (code), client_id (consumer key from Connected App) and redirect_uri (callback URL from connected app)
      • optional parameters: code_challenge, display, immediate, login_hint, nonce, prompt, scope and state.
      • as user interacts with authorization endpoint directly application never sees user credentials.
      • After Salesforce confirms that the client application is authorized, the end user’s web browser is redirected to the callback URL specified by the redirect_uri parameter
    • After the user approves access, the web server receives a callback with an authorization code.
      • Salesforce appends code (auth code that consumer can use to obtain access and request tokens, auth code expires after 15 mins) and state (passed in initial request) values to the authorization information.
    • After obtaining the authorization code, the web server passes back the authorization code to get a token response.
      • Application extracts the auth code and passes it in a POST request to Salesforce for an access token. This request is sent to token endpoint
      • End Point: such as https://login.salesforce.com/services/oauth2/token
      • Required Parameters: grant_type(authorization_code) , client_secret (consumer secret from connected app if Require Secret for Web Server Flow setting is enabled), client_id (consumer key from connected app), redirect_uri (callback URL from connected app), code (auth code from earlier step).
      • Optional Parameters: client_assertion, client_assertion_type, code_verifier, format.
      • Salesforce also supports Basic Authentication scheme that helps to send client id and client secret in authentication header instead of sending them in the body of POST request.
    • After validating the authorization code, Salesforce passes back a token response. If there’s no error, the token response includes an access code and additional information.
      • if the request is successful, server response contains access_token, token_type (Bearer), refresh_token, instance_url, id, issued_at, signature,
      • both access_token and refresh_token needs to be protected by the client.
    • After the token is granted, the web server accesses the user’s data.
  • Flow
    • Screen Shot 2020-01-01 at 10.36.08 PM.png
  • After a web server has an access token, the client can use the token to access Salesforce data on the end user’s behalf. If the access token becomes invalid, the client can use a refresh token to get a new access token.

User Agent Flow

  • used by
    • client apps that reside on the user’s device or computer
    • client apps running in a browser using a scripting language such as Javascript.
    • users can authorize desktop or mobile apps to access data using an external or embedded browser
  • client application requests the authorization server to redirect the user to another Web server or resource which is capable of extracting the access token and passing it back to application.
  • uses the “Implicit” grant type, which gets only access tokens and is optimized for public clients
  • Flow
    • Screen Shot 2020-01-02 at 2.28.41 PM.png
  • Steps
    • application redirects the user to appropriate authorization end point.
    • User logs into the Salesforce with their credentials.
    • Once authorization is granted, auth endpoint redirects the user to the redirect URL. It appends with following access_token, token_type, refresh_token, scope, state, instance_url, id, issued_at, signature.
    • Application uses the provided access token and refresh token to access protected user data.
  • Considerations:
    • if authenticating using JavaScript, call window.location.replace() to remove callback from the browser’s history
  • What happens when an OAuth 2.0 user-agent flow is used?
    • users authorize your desktop or mobile app to access their data.
  • What client types can use the user agent flow?
    • client apps (consumers) that reside on the user’s device or computer.
  • How does the user-agent flow work?
    • 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.

JWT Bearer Token Flow

  • used
    • to authenticate servers without interactively logging in each time the servers exchange information.
    • selected for server-server API integration
    • uses a certificate to sign the JWT request
  • JWT = the format of the request
  • This flow never issues a refresh token
  • Steps
    • The developer creates a connected app or uses an existing one and can optionally register an X509 Certificate. When the connected app is saved, the Consumer Key (OAuth client_id) and Consumer Secret are generated and assigned to the app.
    • The developer writes an app that generates a JWT and signs it with the certificate.
    • The JWT is posted to the token endpoint
    • The token endpoint validates the signature using the certificate registered by the developer.
    • The token endpoint validates the audience (aud), issuer (iss), validity (exp), and subject (sub) of the JWT.
      • aud: authorization server as an intended audience. Use authorization server url for this.
      • iss: should contain OAuth client_id or the connected app for which the certificate is registered.
      • exp: expiration time of the assertion within 3 minutes.
      • sub: user name of salesforce user or community user. prn can be used instead of sub.
      • JWD must be signed with RSA SHA256
    • Assuming that the JWT is valid and that the user or admin authorized the app previously, Salesforce issues an access_token.

Device Authentication Flow

  • Can be used for command-line applications
  • Can be used for applications with limited input and display capabilities, such as appliances, TVs and IoT
  • Users connect these to Salesforce using a browser on desktop or smartphone
  • (THINK Philips Hue, Sonos, app-controlled washing machines, Amazon Echo Dot)
  • Steps
    • The device requests authorization from Salesforce.
      • POST request is sent to authorization end point
      • Required Parameters: response_type (device_code), client_Id (consumer key from connected app)
      • Optional Parameters: scope (access scope defined in connected app)
    • Salesforce verifies the request and returns the following: human-readable user code (verification code for end user, 8-digits, entered at the verification URL), verification URL, device code (verification code for device, valid for 10 mins), and minimum polling interval (in seconds).
    • The device displays the user code and instructs the user to enter it at the specified verification URL.
    • On a separate device that has more developed input capabilities, such as a desktop computer or smartphone, the user opens a browser.
    • The user navigates to the verification URL and is prompted to enter the user code. If the code is valid, the user is prompted to log in if not already logged in.
    • After successful login, the user is prompted to allow the device to access Salesforce data.
    • After displaying the user code and verification URL, the device starts polling the token endpoint for authorization. Polling frequency can’t exceed the minimum polling interval. The device continues polling until the user has allowed (or denied) access, or the user code has expired
      • Polling request contains grant_type (device), client_id, client_secret, code
    • If allowed, the authorization server returns to the device an access token, a refresh token if requested, and other information..
    • After the access token is granted, the device can use it in API requests to access data on the user’s behalf and use a refresh token to get a new access token if it becomes invalid.
  • Flow
      • Screen Shot 2020-01-02 at 3.42.25 PM.png

Asset Token Flow

  • are used to request an asset token from Salesforce for connected devices
  • What are the benefits of combining the issuing and registration of asset tokens within an Asset Token Flow?
    • Efficient token exchange
    • Enables the automatic linking of devices to Salesforce Service Cloud asset data
  • What happens in an asset token flow?
    • An OAuth access token and an actor token are exchanged for an asset token
  • Steps
    • Create a new connected app or use an existing one that has asset tokens enabled and required settings configured.
    • Get an access token so that you can request an asset token.
      • acquire access token using any app that supports the OAuth 2 token exchange protocol. Examples include authorization code exchange, OAuth token flow or JWT bearer token flow.
    • Create your asset token JWT.
      • Endpoint: token end point
      • Required Parameters:
        • grant_type (urn:ietf:params:oauth:grant-type:token-exchange
        • subject_token_type (urn:ietf:params:oauth:token-type:access_token
        • subject_token ( value must be access token)
      • Optional Parameters
        • actor_token_type: optional unless actor_token is specified. Value must be urn:ietf:params:oauth:token-type:jwt_
        • actor_token: JWT containing metadata about asset.
    • Create your actor token payload JWT.
    • Understand how Salesforce attempts to register a new or existing Asset using information from the actor token.
    • Create your actor token JWT.
    • Post your asset token request to the token endpoint.
    • If the asset token JWT is valid, Salesforce issues your asset token in an access token response.

SAML Bearer Assertion Flow

  • Enables applications to reuse an existing authorization by supplying a signed SAML assertion
  • The app is authorized by assigning a digital signature to the SAML assertion
  • It is similar to the refresh token flow within OAuth.
  • It is not required for the client to store the refresh token and no need to pass the client_secret to the token endpoint while posting SAML assertion to the OAuth token endpoint.
  • Steps
    • The developer creates a connected app and registers an X509 Certificate. This certificate corresponds to the private key of the app. When the connected app is saved, a consumer key (OAuth client_id) is generated and assigned to the app.
    • The developer writes an app that generates a SAML assertion and signs it with the private key.
    • The assertion is posted to the token endpoint
      • Endpoint: token end point for customer or internal (similar to JWT Bearer token flow)
      • Required Params:
        • grant_type: urn:ietf:params:oauth:grant_type:saml2-bearer
        • assertion – SAML bearer assertion encoded using base64url
      • Optional Params
        • format – oAuth flow using token parameter or HTTP Accepts header
        • scope – combination of scopes issues from previous access tokens
    • The token endpoint validates the signature using the certificate registered by the developer.
    • The token endpoint validates the audience, issuer, subject, and validity of the assertion.
    • Assuming that the assertion is valid and that the user or admin authorized the app previously, Salesforce issues an access token.
      • use same format as Authorization_code flow although refresh _token is never issued.

SAML Assertion Flow

  • An alternative flow for orgs who are already accessing Salesforce via SAML
  • used when the customer wants to access the web services API in the same way, i.e. using signed assertions
  • This can be used only inside a single org.
  • No need to create a connected app to use this flow.
  • Authenticating with the SAML assertion flow doesn’t invoke login flows. That is, you can’t apply login flows to API logins or when sessions pass to the UI through frontdoor.jsp from a non-UI login process.
  • Also, communities don’t support the SAML assertion flow.
  • Refresh token is never issued in this flow.
  • What is the difference between a SAML Bearer Assertion Flow and a SAML Assertion Flow?
    • While both flows make use of SAML assertions that contain signed certificates, SAML Assertion Flows are used when organizations ALREADY use SAML to access Salesforce and they want to use the Web Services API in the same way.
  • Steps
    • Configure SAML for your org. SAML version 2.0 is required.
    • Exchange a SAML assertion for an access token.
      • Endpoint: Token endpoint
      • Required Params: grant_type – assertion, assertion – base64URL encoded SAML Response, assertion_type (urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser)
      • Optional Params: format (urlencoded, json(default), xml)
    • Salesforce sends the response.
      • access_token, token_type (Bearer), id – Identity URL that can be used for querying additional information.
    • Use a JSON parser to process the response and extract the access_token.
  • Which OAuth flow does not require you define a connected app?
    • SAML Assertion flow

Username and Password

  • should only be used for testing
  • pass hard-coded username and password details back and forth
  • are ineligible to receive a refresh token
  • Steps
    • The consumer uses the user’s username and password to request an access token (session ID.)
      • POST request is sent to the toke end point
      • EndPoint: https://login.salesforce.com/services/oauth2/token
      • Required Parameters: grant_type (password), client_id (consumer key from connected app), client_secret (consumer_secret from connected app if Require Secret for Web Server Flow is enabled), username (end user’s user name), password (end user’s password (appended with security token).
    • After the request is verified, Salesforce sends a response to the client that includes access token.
      • Response contains access_token, instance_url, id, issued_at, signature.
      • No Refresh token
    • After a consumer has an access token, it can use the access token to access Salesforce data on the user’s behalf.
  • Flow
    • Screen Shot 2020-01-02 at 3.09.00 PM.png
  • When should you use the Username-Password OAuth flow? What are things you can do to minimize risk when using this flow?
    • You should only use the username and password flow in situations where a user cannot be present at application startup, or with highly privileged applications.
    • In this instance, you should carefully set the API user’s permissions to minimize its access as far as possible, and protect the API user’s stored credentials from unauthorized access.

Refresh Token Flow

  • The consumer uses the existing refresh token to request a new access token.
  • After the request is verified, Salesforce sends a response to the client.
  • Session timeout for access token can be configured from Session settings.

Miscelinious

  • Which OAuth flows allows the ‘Use Digital Signatures’ ?
    • JWT Bearer Token or SAML Bearer Assertion flow
  • Which two OAuth 2.0 flows can be used with Force.com Canvas?
    • Web Server OAuth Authentication Flow & User-Agent OAuth Authentication Flow
  • Callback URL – Depending on which OAuth flow you use, this is typically the URL that a user’s browser is redirected to after successful authentication. As this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTP (HTTPS) or a custom URI scheme
WebServer Authentication User Agent Username Password SAML Bearer Assertion JWT Bearer Token Device Authentication Asset Token SAML Assertion Refresh Token
Use case Apps hosted on a secure server. Uses Authorization grant type Client apps that reside on user’s device or computer. Client apps running in a browser using a Scripting language like JavaScript, Uses Implicit Grant type Can be used for Testing by passing username and password Enables applications to reuse an existing authorization by supplying signed SAML assertion To authenticate servers without interactively logging selected for server-server API integration uses a certificate to sign JWT request Can be used Command line applications Can be used by applications with limited input and display capabilities Used to request asset token from Salesforce for connected devices. OAuth access token and actor token are exchanged for an asset token for orgs already accessing salesforce using SAML renews tokens issued by webserver or user-agent flows
Developer app None None None Generates SAML Assertion and signs with Private key SAML Assertion Contains (issuer, audience, recipient, subject) Generates JWT and signs with Certificate JWT Token: aud, iss, exp, sub None Create Actor token Payload JWT Create Actor Token JWT
Endpoint authorization, token authorization token token (customer or internal) token (customer or internal) authorization, polling authorization, token for getting access token, token for getting asset token Token (internal) token
Required Params Authorization: response_type (code), client_id, redirect_uri Token: grant_type (authorization_code), client_secret, redirect_uri, code(auth code from earlier step) response_type (token), client_id, redirect_uri grant_type (password), client_id, client_secret, username, password (appended with security token) grant_type(urn:ietf:params:oauth:grant_type:saml2-bearer), assertion (SAML Assertion) grant_type (urn:ietf:params:oauth:grant-type:jwt-bearer), assertion (JWT bearer token) Authorization: response_type (device_code), client_id Polling: grant_type(device), client_id, client_secret, code Authorization: parameters depends on OAuth flow selected Token: grant_type (urn:ietf:params:oauth:grant-type:token-exchange), subject_token_type (urn:ietf:params:oauth:token-type:access_token), subject_token: value must be access_token, actor_token_type (urn:ietf:params:oauth:token-type:jwt), actor_token(JWT containing metadata about asset) grant_type (assertion), assertion (base64URL encoded SAML response), assetion_type (urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser) grant_type (refresh_token), refresh_token, client_id, client_secret or client_assertion, client_assertion_type,
Optional Params Authorization: code_challenge, display, immediate, login_hint, nonce, prompt, scope, state Token: client_assertion, client_assertion_type, code_verifier, format display, scope, state None format, scope format, scope scope format (urlencoded or json or xml) format(urlencoded or json or xml)
Response Authorization: Authorization code Token: access_token, token_type (Bearer), refresh_token, instance_url, id, issued_at, signature access_token, token_type, refresh_token, scope, state, instance_url, id, issued_at, signature access_token, instance_url, id, issued_at, signature access_token access_token Authorization: human readable user code, verification URL, device code, minimum polling interval Polling: access_token, refresh_token if requested Authorization: access_token and other information Token: header, payload, signature access_token, token_type (Bearer), id access_token, token_type (Bearer), instance_url, id or sfdc_community_url & sfdc_community_id, signature,issued_at
Considerations Server must protect secret. Users can authorize desktop or mobile apps to access data using an external or embedded browser Client application requests auth server to redirect the user to another Web server or resource which is capable of extracting the access token and passing it back to application. If authenticating using JavaScript call window.location.replace() to remove callback from the browser’s history Ensure that username and password are not hacked Refresh token is never returned in this flow App is authorized by assigning a digital signature to the SAML response It is similar to refresh token flow Not required by client to store refresh token and not required to oass client_secret to the token endpoint Register an X509 Certificate on the connected app. Assertion must be signed according to XML Signature specification and must be encoded with base64url encoding while posted to endpoint JWT must be signed with RSA SHA256 Users connect these to Salesforce using a browser on desktop or smartphone. User has to navigate to Verification URL and enter the user code and then login and allow the device. After displaying user code and verification URL device starts polling the token endpoint for authorization. An access token must be associated with a connected app that has asset tokens enabled. Get access token using any OAuth2.0 token exchange protocol. Can be used only in a single org No need to create a connected app Communities do not support. Login flows are not invoked, Refresh token is never issued can use HTTP Basic authentication scheme instead of sending client credentials
Advantages Application never sees credentials Efficient token exchange, enables for automatic linking of devices to Salesforce Service Cloud asset data
Post Views: 19,270

Leave a Reply to Kingdom77ID.com Cancel reply

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