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.