What’s New with Named Credentials
Named Credentials are used to authenticate from Salesforce to an external system. And if you’re a Salesforce architect you need to know how to use them to design secure outbound integrations. In this blog I talk with Ross Belmont, Director of Product Management, Platform Services, to explore what’s new with Named Credentials.
Susannah: Most folks who’ve been around Salesforce for awhile know that Named Credentials are not new.
Ross: Exactly, Named Credentials have been part of the Salesforce platform for more than a decade.
Susannah: But in case anyone needs to catch up, when we talk about Named Credentials we’re referring to the features that handle authentication for outbound integrations. With Named Credentials you define the endpoint and its authentication details declaratively. Then behind the scenes, Salesforce handles the heavy lifting of the authentication protocol implementation and endpoint allowlisting (among other things).
Using Named Credentials is pattern all architects should be utilizing instead of trying to handle authentication details in your Apex code. But lately things have been changing with Named Credentials. Ross, what should architects know about these changes?
Ross: In the last few years, we’ve revamped the architecture underneath Named Credentials to expand what’s possible and prepare for future growth. This expanded infrastructure is focused around two new ideas.
Susannah: OK, what should architects focus on first?
Ross: The first thing to know is that authentication is now separated from the endpoint definition. Separating them allows the same authentication configuration to be used for multiple endpoints.
For example, you might authenticate against Google’s OAuth service, and then make calls to both the Google Drive API and the Google Calendar API. The endpoint is still defined via the Named Credential object, but now it has a lookup to something called an External Credential.
Susannah: External Credentials, that’s new to me. How are they different from Named Credentials?
Ross: The External Credential captures the authentication details, and the Named Credential holds the endpoint. The two are separate, but they work together.
The connection between a Named Credential and an External Credential is a straightforward lookup, similar to how a Contact is related to an Account. You can view the External Credential and see all the associated Named Credentials in a related list. And just like with Accounts and Contacts, you’ll want to create the External Credential first, and then create the Named Credential that looks up to it.
Susannah: You mentioned two new ideas that went into the revamped Named Credential architecture. What is the second?
Ross: Secondly, permissions are now explicit instead of implicit.
Users now need explicit permission to make callouts with a given set of credentials. This extends to ISVs as well. If a managed package needs to make a callout using a Named Credential created by an administrator in the org, that package’s namespace needs to be allowlisted on the credential.
Susannah: Anything else notable about the changes to the architecture?
Ross: The Named Credential object now has a Type field that functions like a Record Type designation. Newer credentials will be reflected with the Type of Secured Endpoint, and in the list view you can see both the Type and the associated External Credential.
The original iteration of Named Credentials is reflected with the Type of Legacy. Legacy credentials store all settings on a single setup object. Older credentials don’t have a lookup to an External Credential. Here’s what it looks like in Setup in Lightning:
Susannah: How can people get started with External Credentials?
Ross: Some people think they have to “switch” from Named Credentials to External Credentials, but that’s not true. They’re used together and it’s available in Setup today. You’ll create both, and link them together. The Named Credential object is still critical, not least because it still is referenced by Apex code that uses that credential in a callout. We don’t want to change how people write Apex code or build Flows.
Susannah: OK, that makes sense. But what about the explicit permissions you mentioned earlier?
Ross: Users now need permissions to make callouts using specific credentials. It’s similar to how we added the requirement a few years ago that users need explicit permission to run an Apex class. A key principle for us at Salesforce is that everything is secure by default.
Susannah: I know that one of the reasons your team made these changes to the architecture is to continue to invest and advance capabilities around trust. Walk us through how we can use these changes with Named Credentials to build more secure integrations.
Ross: When creating an External Credential, you now also create one or more Principals underneath it, each reflecting the identity of the caller in the external system. AWS also uses the term Principal to represent the same idea. Many times, this identity is an “integration user” or “service account” that does not correspond to an individual human being. Principals like that typically hold an API key or other secret. The permissions make it explicit that a given User has been granted access to that key or secret, not in its raw form, but within the context of a callout. The callout will be blocked if the calling user hasn’t been granted permissions to the Principal.
You’ll see External Credential Principal Access as a new option available when configuring a Permission Set. You could also associate this with a Profile, but the best practice is to use Permission Sets and Permission Set Groups. Developers can also manage access by creating SetupEntityAccess records directly via Apex code.
Susannah: You mentioned you can create one or more Principals. When would you need multiple Principals?
Ross: Sales Cloud users could have different access than Service Cloud users, for example. Or perhaps Service Cloud agents have a read access to data in a remote system, but Service Cloud managers also have the ability to read and delete records in that external app.
If a single User is granted access to multiple Principals for the same External Credential, there’s a precedence that can be applied to decide which set of credentials to use. Essentially, admins set a numerical order using a Sequence Number. Multiple principals is a key capability enabled by our updated architecture, and large enterprises with tight access controls for different departments should consider implementing them.
Susannah: This varied level of access reminds me of record sharing in Salesforce.
Ross: Yes, this can enable similar outcomes. Most external systems do not have access controls that are as robust as what we offer around record sharing in Salesforce. Typically, these apps provide some way to define broader roles like “Sales” or “Marketing,” which are often sufficient for integration use cases. Our goal is to enable access that’s as fine-grained as the external system allows.
Susannah: Speaking of the external system, do you have any guidance for architects when integrating with an external application that does support fine-grained access controls?
Ross: Hyperscale providers like AWS do in fact offer very fine-grained access controls, and we encourage customers to take advantage of them to the fullest extent possible. That way, the Salesforce “client app” has minimal, optimized access to the remote system. We enable this via support for AWS’s IAM Roles Anywhere, dynamic scopes in OAuth (which is great for Snowflake), and more. OAuth also offers a path for individual users to have their own auth/access to the remote system, but coarse-grain access (e.g. roles) in external systems is more common.
Susannah: Is there anything else to know about permissions and the new Named Credentials architecture?
Ross: Yes. Users who make callouts will also need access to a new standard object called User External Credentials. This object holds the actual encrypted access tokens or other secret values used to call out the external system. The new architecture stores these values in a data object so that many thousands of them can be persisted in a robust way, and we sidestep security concerns by separating them from metadata (which is exported from orgs in plain text).
Here’s a diagram that illustrates how it all fits together:
[Alt text: A diagram illustrating the new Named Credentials paradigm]
Susannah: OK, we’ve spent a good deal of time talking mechanics, but let’s walk through a real life example of how the Named Principal and User External Credentials are utilized in a system-to-system integration.
Ross: Great idea. While I’m sure you’ve performed the “OAuth handshake” many times to grant one system access to another on your behalf, most integrations are not configured in a way that requires end users to take action. System-to-system integrations are more often configured by administrators directly, and one system is given a means to programmatically “log into” the other. This can be done via certificates, API keys, or other shared secrets (e.g. passwords).
In scenarios like this, a Named Principal is used by multiple Salesforce Users to share the same credentials. When this occurs, you’ll likely be in a situation where all those Users need Modify All permissions to the User External Credentials object. Imagine that User A is first to establish a connection with an external system and obtains an access token. After some time, the token expires. Then, User B uses the same integration, and their activity prompts Salesforce to refresh the token. When the new token is persisted, it overwrites a value in a record created by User A — hence the need for Modify All.
And even though Users have Modify All permissions, they can’t directly view or change the values from the UI, SOQL, or Apex. That access is only used internally when tokens need to be managed.
Susannah: Any other new features that architects should be aware of?
Ross: To facilitate the system-to-system integrations I mentioned earlier, we delivered support for some popular authentication mechanisms: Client Credentials and the JWT Bearer Flow in OAuth, custom claims in JWT authentication, and API keys.
You may recognize the terms Client Credentials and JWT Bearer Flow. Administrators leverage these approaches to enable integrations where an external app needs to call into Salesforce. Now, they can also be used when Salesforce needs to call out to a service running on a hyperscale public cloud like GCP. Since it’s quite common for large vendors to recommend either Client Credentials or the JWT Bearer Flow, we wanted our customers to be able to meet this requirement without writing code.
API keys are relatively simplistic, but also very commonly used. We give you the ability to store the keys in an encrypted manner and attach them to your callouts in the header. You can even use formulas to manipulate the header’s value, further reducing the need to use code to manage authentication. Keeping secrets out of your code is key to maintaining compliance with standards like SOC II Type 2.
A quick note on JWT: technically, the JWT Bearer Flow is different from what we simply call the JWT authentication protocol because the former is part of the OAuth spec. Both use certificates to sign the JWT and increase security, making them an attractive choice. Use whichever one is supported by the external system in question.
Client Credentials, in contrast, uses a Client ID and Secret to identify Salesforce as the “client” application. The ID and Secret function similarly to a simple username and password, so manage those carefully and plan to rotate them occasionally.
Susannah: What’s the best practice for rotating keys?
Ross: This is a great segue into the last major topic we haven’t yet touched on: our configuration API, available in both Apex and via REST (where it’s referred to as the Connect API). You can use this API as a control plane to create and manage credentials, enabling what you might call infrastructure-as-code or policy-as-code.
Susannah: Some architects might be wondering, why not just use the Metadata API to manage my credential setup programmatically?
Ross: While Named Credentials do support the Metadata API, this can only be used to move some configurations between orgs. Unfortunately, you can’t use it move any shared secrets like API keys between your orgs, because that would involve retrieving the secret value from the org in plain text (before deploying it to the target org). You also can’t package these secrets, for the same basic reason. This new configuration API gives you different options to solve that issue, and others we haven’t foreseen regarding setup. You can write code against this new API and blend it into your CI/CD pipeline.
Susannah: Pretty cool. Any closing thoughts?
Ross: We expect some ISVs to extend their existing custom setup UIs to automate the administrative burden around creating credentials. It’s frustrating when the ISV can predict what the configuration should be, but can’t package the credentials to reduce the setup hassles experienced by our joint customers.
To address this, we made the new configuration API accessible from Apex. Managed package code can create credentials on behalf of the administrator, and all they have to do is flip a toggle switch to enable them for callouts. The ISV can build a UI that matches their brand and unique needs.
We want all our customers and partners to benefit from these new features. Our vision is that you can enable integrations without writing code to manage authentication. Please reach out in the Trailblazer Community and IdeaExchange to engage with us and let us know how it’s working for you and your team!
Conclusion
I hope that this conversation has has provided insight into some of the exciting enhancements available to secure outbound integrations. Security is the first priority when it comes to building Well-Architected Salesforce solutions, which is why it’s so important for architects to be aware of the latest changes to the platform. Interested in learning more about building secure solutions? Check out the extended conversation I had with Ross below, and explore the Well-Architected-Secure whitepaper to learn even more about organizational, session, and data security.
About the Authors
Ross Belmont is a Director of Product Management covering Platform Data Services. He has more than a decade of experience with the Salesforce ecosystem.
Susannah Plaisted is an Architect Evangelist at Salesforce. She is passionate about empowering and inspiring Architects and ensuring they have the tools and skills they need to build better solutions.
