Whether you are a Salesforce Customer or Partner, designing a very secure solution is always one of the most important goals. A key aspect of the platform’s security is how it stores and manages external system credentials. In this article we want to review standard and custom options that Salesforce has to offer for this purpose.
Standard Metadata Features
Salesforce provides a few standard metadata features for managing auth information for external systems.
- External Credential is where credentials are entered and the supported authentication protocol is selected. Additionally, a permission set is used to associate user access to these credentials. Depending on the protocol, an auth provider may need to be configured in Salesforce before OAuth credentials can be selected here. External credentials cannot be used directly and are created to be referenced in named credentials which are used by the platform.
- Named Credential is where an external credential is associated with an entered base endpoint. Named credentials are used in apex code, external services or external data sources. Usage of named credential allows Salesforce to construct the target endpoint and optional authorization of custom headers of an HTTP request. The platform also exposes named credential information in the shape of few merge fields which allows further customization of the outbound request if needed. Example of a simple usage in apex could look like below:
req.setEndpoint(‘callout:My_Named_Credential/some_path’);
Standard Metadata Features Benefits
The standard features provide decent convenience and flexibility to accommodate different types of auth patterns that are used in the industry.
The convenience comes from some of the following facts:
- Salesforce securely stores the sensitive auth information for you, along with supported protocol’s tokens e.g OAuth’s Access token. Referencing code does not need to manage any of this information.
- User experience wise, there is a unified place in Salesforce setup to enter all information needed to connect to an external system
- Reusability is supported, as the same set of external credentials can be used for different named credentials (endpoints).
The flexibility comes from some of the following facts:
- External credentials can be declared as “Custom” which leverages custom headers, enabling you to support a diverse range of auth designs. Custom headers are especially helpful, as they are formula based and dynamically evaluated.
- Named credentials can be configured to allow formulas in HTTP header or body and to auto generate authorization header if needed. This enables you to structure the HTTP request dynamically in apex code as well.
Standard Metadata Features Customizability
Overall, the combination of these 2 features caters to common auth scenarios and provides customizability for many routes. However there could still be reasons to consider a custom auth approach, for example:
- The end user experience demands a more simple or flexible process than what standard platform features require the users to navigate through.
- In standard configuration, the required permission set association to external credentials could be seen as an undesirable maintenance step in certain scenarios.
- Technically the auth protocol may not be directly supported by standard features and the custom options available appear cumbersome to implement.
Custom Metadata Features
If you choose to set up a custom approach for external auth then the good news is that the platform provides you with features to leverage in a custom design. There are few key components that you will want to get started with when it comes to storing sensitive auth information:
- Remote Sites: Base URL of any external endpoint that Salesforce needs to reach out to, needs to be listed as a remote site in Salesforce setup. Example, Auth endpoint or any data endpoint. An alternative could be to use a named credential without auth information and reference it as the target endpoint. Named credentials can be referenced in apex via API name but the entry user experience could be undesirable as a higher number of clicks are needed to set them up, even without the auth information.
- Custom Metadata Types: Application identifying auth information that does not change typically should be stored in custom metadata. Examples would include external auth endpoint, OAuth scopes, Client ID or Client Secret. The exact needed fields depend on the authentication protocol selected. For ISV partners, this setting should be declared as ‘protected’, so that the end customer cannot directly access the sensitive information stored. Only apex code belonging to the same managed package can interact with the protected custom settings.
- Custom Settings: Auth information that changes per Salesforce instance can be stored in custom settings. Example, a refresh token that needs to persist. For ISV partners, an additional example could be Client ID, if it changes for different customers. Depending on the exact storage needs, the wall between custom metadata types and settings is flexible in terms of what information should live in which of the two. The protected declaration would also be recommended for custom settings that belong to a managed package.
- Platform Cache: Transient authentication session information can be stored in platform cache. Example, an access token. For ISV partners, Salesforce provides free cache capacity to use if you have an AppExchange certified and security reviewed managed package. It is recommended for managed packages to leverage their own packaged partition for storing secure information. Warning: Platform cache is only available for Enterprise Edition orgs and above. If you try to install your application into a Professional or Essentials Edition org, the package will not install.
Custom Metadata Features Needing Additional Customizations
In order to support custom auth routes, the application will need few additional customizations that go beyond storing information. Here are a few examples:
- Based on authentication protocol, if an authorization step is required which involves a user navigating externally to approve the connection, then a callback page and controller would be required to read the URL parameters. Callback page helps the front end approval connect with subsequent server side steps.
- Apex code for API communication should use appropriate Util and Service classes to have a common approach of custom building the authorization part of HTTP requests.
- Apex classes and methods would also be required to manage the read and write operations on auth information that is stored across platform features such as custom settings, custom metadata types etc.
Implications for ISV Partners
Choosing between standard and custom approaches have a few more implications for ISV partners because of packageability considerations of certain metadata types, here are few points to note:
- Even if you package a named credential, the subscriber still needs to reauthenticate in the setup page. For post-install application configuration, if a custom experience is desired then using a standard feature means that the subscriber may have to visit named credentials standard setup page.
- Subscribers are not able to locally override some of the named credential details such as an endpoint. If different customers need to connect to different endpoints, then a more flexible route should be considered.
- Certificates are not packageable and subscribers have to go through additional configuration steps to enable dependent auth setups.
Depending on the exact product experience desired, certain features are more suitable for packaging vs unmanaged deployment. Salesforce metadata coverage report should be reviewed before finalizing a package’s scope. Security design is carefully assessed by Salesforce experts during an application’s security review process, which allows it to be listed on the Salesforce AppExchange.
Leverage the Experts
Salesforce authentication and authorization is a big topic whether we speak about inbound or outbound scenarios but I hope that this topic highlighted some helpful design considerations for outbound auth. Whether you are a Salesforce customer or partner, if you require support to design and build intuitive identity solutions then feel free to reach out. As a Master Product Development Organization (PDO), CodeScience has deep and extensive experience in solving a diverse range of identity and access challenges.
