JWT / SAML Assertion Bearer Flows

Secure server-to-server integration without real time user involvement. Client specifies user in a JSON web token (JWT) or SAML format XML assertion and proves its own identity by appending a signature. JWT Bearer token flow is Ideal for application which access sfdc only through API as there is no UI involved. For example ETL tools or middleware.

Additional requirements

  • Client can manage private key of an X.509 certificate
  • Certificate available to auth. server
  • User authorisation has been provided
  • Up to date security measures

What else to know

  • Client secret not required
  • Flows will not return refresh tokens
  • Additional user claims can be included
  • User authorisation mechanism is up to individual implementation. For Salesforce as auth. server, options are:
    • Admin approved users are pre-authorized – If user assigned a profile / permission set associated with app, no need for them to approve for flow to be used
    • All users may self-authorize – User must have approved at least once

OAuth 2.0 JWT Bearer Token Flow

  • Ideal for application which access sfdc only through API as there is no UI involved. For example ETL tools or middleware.
  • A JSON Web Token (JWT) enables identity and security information to be shared across security domains. 
  • JWT is basically a JSON file consisting of a header and claims object, where the header contains the signature algorithm and the claims object contains specific information such as the username and consumer key. At a high level, you will then sign the JSON object with the private key of your certificate and send the JWT to Salesforce to obtain an access token.
  • When a client wants to use this flow, posts an access token request that includes a JWT to Salesforce’s OAuth token endpoint. Salesforce authenticates the authorized app through a digital signature that is applied to the JWT. 
  • Digital certificates are required in this flow. Upload certificate (X509 ) to connected app which will be used to authenticate JSON web tokens.
  • External application send request for access token by passing JWT token in body. SFDC server validate JWT and return access token to external app.
  • No refresh token is returned in this flow. So if access token expires then send request to generate access token again.

What else to know – JWT Bearer

  • JWT attributes:
    • aud = Auth server identifier (for Salesforce, login URL)
    • iss = Client identifier (for Salesforce, client id)
    • sub = User identifier (for Salesforce, username)
    • exp
  • Used in SFDX CLI authorisation
  • Available for named credentials callouts

OAuth 2.0 SAML Bearer Assertion Flow

  • A SAML assertion is an XML security token issued by an identity provider and consumed by a service provider.
  • The external app or client isn’t required to store client_secret.
  • If you use active directory or LDAP as identity provider, then you will use SAML assertion from your SSO flow to obtain an access token to Salesforce.
  • This flow used SAML assertion (XML token generated by Identity provide) and applied digital signature to it using certificates.
  • In connected app, you upload this certificate (X509 ) containing private key. This key should be used while signing SAML asseration(base 64 encoded).
  • The SAML assertion is posted to the OAuth token endpoint, which in turn processes the assertion and issues an access_token based on prior approval of the app(users are pre- authorized in connected app). 
  • This flow also return only access token not refresh token

What else to know – SAML Assertion Bearer

  • SAML assertion is XML (Base64 encoded for auth. server)
  • SAML attributes:
    • Audience = auth. server identifier
    • Issuer = issuing entity. For Salesforce, this
    • must be the client app’s client_id
    • Subject = User
  • General SAML validations must be implemented by auth. Server


YouTube video

Considerations for choosing JWT / SAML assertion bearer

  • Best practice for server to server OAuth
  • Ideal flow for continuous integration, middleware, org to org integration, integration with public web site and many other use cases where real time user interaction not desirable
  • Initial approval must be considered

Further Learning

Amit Chaudhary
Amit Chaudhary

Amit Chaudhary is Salesforce Application & System Architect and working on Salesforce Platform since 2010. He is Salesforce MVP since 2017 and have 17 Salesforce Certificates.

He is a active blogger and founder of Apex Hours.

Articles: 466

One comment

Leave a Reply

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