When building an integration within Salesforce to an external system, a developer might decide that they will connect directly to the API rather than develop against an existing package. Developers that choose to work within an established package will have access to the most common actions required for an integration, but may have less flexibility with implementing customizations than if they develop their own integration using the API directly. . If a developer chooses to develop using the API of a product, they must decide how they will authorize the user in Salesforce to make API requests. Two of the most common methods for authenticating to an external system are Authorization Code Grant and Impersonation Grant. Deciding on which grant type to use should be based on what level of access the user will have to the external system.
Authorization Code Grant:
Authorization grant is used when an application is required to authorize each user in Salesforce with their own external account. The user will enter a username and password for the external system before access can be granted. Authorization grant is beneficial when each of your users have separate logins. For example, when connecting to DocuSign, every user might have their own login credentials. The developer might build a button in Salesforce that initiates the Authorization Code Grant flow that navigates the user to an external page where they will log into DocuSign. An authorization code is granted, and the user is returned to Salesforce where an access token is generated. The user can then make calls to the DocuSign API using the generated access token. Through this process, each user can make callouts from Salesforce to DocuSign using their own individual login credentials.
Impersonation Grant:
If Salesforce users need to access an external application, but do not have their own individual logins to that system, a developer might choose Impersonation Grant over Authorization Code Grant. Impersonation Grant allows all users to assume the authorization level of an admin when interacting with an application. Suppose users within a community are required to sign a DocuSign form. Not all community users will have their own DocuSign login credentials. In this case, we would store the credentials for an admin user in a custom metadata type and use those credentials to allow users to impersonate the access level granted to the admin user. The community users will not be required to enter a DocuSign username and password in order for Salesforce to make API calls because Salesforce has already stored the credentials for the DocuSign Administrator.
One common standard for using Impersonation Grant is JWT Grant. JWT stands for JSON Web Token, which is a specific format used for sending information securely through a callout. JWT grant paired with an RSA key, allows an external application to verify which user has made a callout. When building an RSA key, a public and private key is generated. Since only the application you are connecting to knows the private key, it can verify the signature portion of the JWT token, ensuring the message has originated from a verifiable source.
Building a JSON Web Token
A JWT token consists of three encoded strings concatenated together, each portion separated by a period. They are the header, payload, and signature.
1. Header
The header is often the simplest portion of the JWT token. It contains the algorithm that will be used and the type which in this case will always be JWT. The algorithm represents the signing algorithm. The entire header is then base 64 encoded to form the first portion of the JWT. The header usually looks like:
2. Payload
The payload, or body, contains the message that will be received by your web service. This could take any form that your application requires but should also be base 64 encoded.
3. Signature
Finally, the signature is the portion of the JWT token that verifies who is sending the message. This contains the private RSA key, which is also encoded, possibly using the Salesforce Crypto class.
Once each portion is complete: the final JWT can be concatenated using the following:
Once encoded the string will have a format that matches the below example. The encoded header is in red, the encoded body in purple, and the encoded signature in blue.
For additional information on building your own JWT, visit https://jwt.io/
Once your JWT token has been created, it can be set to the body of the callout, and you now have a secure method of sending information through a web service. The application holding the RSA private key will be able to verify the sender of the data using the signature portion of the JWT token.
When using JWT grant or Authorization Code Grant, here are some tips that can aid in the process:
Impersonation Grant does not require a login screen: When using Impersonation grant with JWT, the user is never taken to a login screen. This could simplify your integration, because handling the redirect uri is no longer necessary.
Store integration setup parameters in Custom Metadata: This way, ids related to authentication aren’t referenced directly in code and will be more flexible. It would be inefficient to update an Apex class every time we wish to switch between a test endpoint and a production endpoint. Making these changes in Custom Metadata is often easier and more maintainable.
Utilize Postman: Before writing any Apex to handle sending a callout, it is helpful to test the endpoint in an API platform like Postman. This is used for troubleshooting any issues with the API early in the process. If the API doesn’t behave as expected within Postman, that behavior is unlikely to change once ported to Apex.
The decision to use JWT in a callout should depend on whether the web service that you are connecting to requires it. Developers have a bit more flexibility when choosing Authentication Grant or Impersonation Grant. Deciding which type to implement relies mainly on whether users of your application will be logging in with their own individual accounts to the external system, or if they are sharing an administrator login.
