Web Server Authentication Flow

  • are for apps hosted on a secure server
  • must be used when the server must protect the secret
  • uses the “Authorization Code” grant type, which is optimized 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
  • 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
  • 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

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
  • 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.

Miscellaneous

  • 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

Traceability Matrix

  •  WebServer AuthenticationUser AgentUsername PasswordSAML Bearer AssertionJWT Bearer TokenDevice AuthenticationAsset Token SAML AssertionRefresh Token
    Use CaseApps 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 passwordEnables applications to reuse an existing authorization by supplying signed SAML assertionTo 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 AppNoneNoneNoneGenerates 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
    NoneCreate Actor token Payload JWT
    Create Actor Token JWT
    NoneNone
    Endpointauthorization, tokenauthorizationtokentoken (customer or internal)token (customer or internal)authorization, pollingauthorization, token for getting access token,
    token for getting asset token
    Token (internal)token
    Required ParamsAuthorization: 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_urigrant_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, stateNoneformat, scopeformat, scopescopeNoneformat (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, signatureaccess_token, instance_url, id, issued_at, signatureaccess_tokenaccess_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), idaccess_token, token_type (Bearer), instance_url, id or sfdc_community_url & sfdc_community_id, signature,issued_at
    ConsiderationsServer 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 SHA256Users 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
    AdvantagesApplication never sees credentialsEfficient token exchange, enables for automatic linking of devices to Salesforce Service Cloud asset data
     

References

One Comment

  • Jack Peterson Reply

    Very quickly this website will be famous among all blogging people, due to it’s fastidious articles or reviews.

Leave a Reply to Jack Peterson Cancel reply

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