Named Credentials vs Remote Site Services

In the last few posts in this mini series on Named Credentials I’ve been looking at the new form of Named Credentials and specifically the changes made in the Summer ‘23 release. But Named Credentials are not the only way to make callouts to external endpoints on the Salesforce platform. I was recently advising a team on some new functionality and they wanted to use Remote Site Settings. My strong recommendation was Named Credentials. Let’s explore why.

First of all why might a team (or individual) prefer Remote Site Settings? The first reason might simply be force of habit. Remote Site Settings have been around since API 19, Named Credentials since API 33 (both according to the Metadata API documentation). A lot of examples, including Trailhead, shows Remote Site Settings rather than Named Credentials. This alone hardly makes a compelling argument for Remote Site Settings. In fact it might favour the opposite argument - if Remote Site Settings were so good why were Named Credentials added?

The next argument for Remote Site Settings might be perceived complexity. For some reason Named Credentials are perceived as more complex. This is certainly true form an initial setup perspective - a Remote Site Setting is just a label and URI but a Named Credential can require a whole heap fo setup, authentication details and more. However once this is done for a Named Credential every callout using that Named Credential gets the authentication for free. With a Remote Site Setting you need to do all the authentication manually. This can be both complicated, especially with OAuth, and error prone. So strike two for Named Credentials

So now that we’ve looked at this from the side of Remote Site Settings what about from the Named Credentials side? The most obvious advantage is the authentication advantage already discussed above. In most cases this would be enough. But what about where no authentication is required? Well Named Credentials still offer advantages (assume we are talking about new-form Named Credentials):

• Arbitrary data can be stored with the External Credential and used in custom headers that are automatically added to the request without Apex code

• Named Credentials require permissioning to use via a Permission Set - Remote Site Settings allow any callout from any code by any user

• Named Credentials can be locked to one or more namespaces - this can be particularly important for ISVs

• Named Credentials effectively separating the business logic from endpoint URI

Let’s examine these advantages. Starting with the last. Separating the business logic from the endpoint URI is a much bigger advantage than it sounds. What happens when the URI changes? Do you want to have to find each and every callout to the endpoint and change them? What if you are an ISV and the endpoint varies for every customer instance? You can use Named Credentials or build your own Custom Setting and string replace in each and every callout. Seems like Named Credentials really win here.

Arbitrary data storage may be helpful in some cases. This is definitely not a strong win in every use case. We saw in a previous post how this data storage capability could be used to implement Basic Auth. It can also be used in other ways. Imagine you are implementing some sort of Jira integration to sell. Jira has two flavours, Cloud and OnPrem. These two flavours have slightly different APIs. You could store which flavour was in use on the Named Credential and switch automatically.

Permissioning should be a big deal for Admins. With a Remote Site Setting you are allowing any code running as any user to access that endpoint. This is a very powerful org-wide permission with no way to restrict it. This is so powerful including a Remote Site Setting in a managed package causes a confirmation to be required to install it. Named Credentials, at least new ones, require a permission set to be linked to the External Credential. This empowers the admin to control which users can run code that access the endpoint. Admins should probably push back harder than they do against packages containing Remote Site Settings

Named Credentials can be further locked down be locking them to a specific namespace. So a Named Credential in a managed package can be locked down just to the code in that namespace. This means that ISVs are not opening up access to arbitrary code. Admins should see this as a significant advantage.

We could envision an event driven integration architecture where Platform Events are fired whenever the integration needs to communicate off platform. The Apex trigger for these runs as a specific named user. The Named Credential is locked to the integration namespace and only this named user has the permission set assigned. This seems like an ideal situation from a security and control perspective

tl;dr There is no reason to favour Remote Site Settings and many reasons to favour Named Credentials. All new code should use Named Credentuals

New Named Credentials and Basic Auth

“Legacy” Named Credentials support a whole host of authentication methods. “New” Named Credentials - not so much. One of the basic things missing is Basic Auth. Sure Basic Auth is pretty outdated and really not as secure as we’d like. But there are still plenty of end points out there that offer Basic Auth and it can be useful. So how can we use the new Named Credentials and still use Basic Auth?

Oh no! No Basic Auth!

Fortunately we can actually have basic auth without writing any code (although a little formula will be required).

Before we get into the configuration details what is Basic Auth? Basic Auth is a header passed on the HTTP request. It’ll look something like this

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

This is the basic auth header for a username of username and a password word of password. It is generated base64 encoding the string <username>:<password> where <username> is the username and <password> is the password. Then prefix with Basic and that’s your header value. Pretty simple right?

So let’s start by creating an External Credential and adding a Principal with a couple of parameters: one for the Username, one for the Password. Salesforce will protect these for us so we don’t have to worry about the encryption at rest etc - it’s handled for us

Now we can create a Custom Header that uses the parameters from the principal. This will use a formula to calculate the Base 64 encoded value discussed above. The formula is

{!'Basic ' & BASE64ENCODE(BLOB($Credential.BasicAuth.Username & ':' & $Credential.BasicAuth.Password))}

• Note that in this formula BasicAuth is the name of the External Credential, Username and Password are the parameter names. This is a bit fiddly! Maybe use the nice new methods discussed in the previous entry to automate the creation of this.

Save the custom header and then Create a Named Credential and add the External Credential to a Permission Set as normal

Summer '23 Named Credentials for Apex Developers

In a previous post I discussed the changes made to Named Credentials in the Summer ‘23 release of Salesforce from an Admin point of view. In this post I’ll examine what this means for the Apex Developer.

Prior to the new form of Named Credentials being introduced in Winter ‘23 there was no “native “ way for Apex developers to interact with Named Credentials (beyond using them in callouts) - named credentials could not be created, modified or deleted from a native Apex API. It was possible to do this using the Metadata API. This involved making a callout and using the user session to do so. In recent months Salesforce has started rejecting managed packages that do this during the security review process. Alternative methods using connected apps and OAuth are possible but using the Metadata API to alter security related metadata could still cause a failure.

There are cases where managed packages may want to offer a guided setup experience which may include creating Named Credentials. In some cases these credentials could be packaged. However in some cases the endpoint host will be subscriber specific so a dynamically created Named Credential will be a better choice. How can an Apex developer continue to offer this?

In the Winter ‘23 release it was possible to create and manipulate a new format Named Credential that used an existing External Credential but not create the External Credential using a pure Apex API exposed in the ConnectAPI namespace.

ConnectAPI.CredentialInput input = new ConnectAPI.CredentialInput();
input.authentication​Protocol = 'OAuth';
input.credentials = new Map<String, ConnectAPI.CredentialValueInput>();
input.externalCredential = 'MyExternalCredential';
input.principalName = 'MyPrincipal';
input.principalType = 'NamedPrincipal';
ConnectAPI.createCredential(input);

The developer name for the External Credential could be retrieved using getExternalCredentials to get a list of all credentials the user can authenticate to.

In Summer ‘23 it appears initially that the final parts of the puzzle are in place. We have the new createExternalCredential method to allow us to create a new external credential using data we gather from the user then create the Named Credential. So all is good!

But think back to the changes introduced in Summer ‘23. The link to the permission set is no longer part of the External Credential. It’s part of the permission set. So creating the External Credential and Named Credential is not enough: the permission set has to be updated. And there is no native Apex API for that. In fact it’s reasonable to assume that this new method is only being made available as it now does not allow Apex to alter the permissions of a user.

So in short you can automate the creation of a non-standard External Credential and Named Credential to automate setup for your users. But you cannot link it to a permission set so the Admin will still have to be prompted to take action

Named Credentials in Summer '23

In Winter ‘23 Salesforce introduced a new model for Named Credentials which split the endpoint definition from the authentication definition. The endpoint definition remains in the Named Credential with one, or more, External Credentials specifying the authentication details. Different External Credentials can be linked to different Permission Sets allowing control over which users have access to which authentication details. Furthermore the Named Credentials can be limited to certain namespaces.

At the same time some new Apex methods were made available to allow manipulation of certain parts of this setup from Apex without having to go through the Metadata API. Which is great but it did not cover all use cases, specifically it did not allow the creation of Named Credentials (although it did allow the creation of External Credentials). For many managed package use cases it’s desirable to create Named Credentials dynamically so the Metadata API was still required.

This small series of blog posts discusses changes and improvements in Summer ‘23 to both from the perspective of an admin using Setup and an Apex developer.

Changes in Summer ‘23

From an admin perspective the big changes in Summer ‘23 relate to the way that an External Credential is linked to a Permission Set. Prior to Summer ‘23 this was managed from the External Credential side. This was slightly odd. As an admin you were changing the access users had to a resource from somewhere other than the Permission Set (or Profile but that’s going away). Any user you assigned the Permission Set to would have access to the External Credential but you could not see that anywhere on the Permission Set. Which is odd.

View fullsize

View fullsize

When I first started exploring the changes in a Summer ‘23 org I was surprised by the changes and could not initially work out how to get a Named Credential working (having created it from Apex as discussed below).

This is because the Permission Set mappings have gone! Without a permission set mapping the Named Credential could not be used as there was no valid External Credential. A quick search around and I found the changes on the Permission Set page instead.

View fullsize

View fullsize

View fullsize

This places the control where you’d expect it as an admin: on the permission set. It’s easy to look at the permission set and see what that permission set is giving access too and somewhat harder to accidentally give users permission when you did not mean to.

This also means that External Credentials permissioning falls in line with the existing Named Credentials permissions on permission sets. This is for legacy Named Credentials so should be something admins are used to.

Any other changes you might have wanted to come to modern Named Credentials will have to wait for a future release. The biggest one from my point of view would be the addition of more authentication types. At least to cover all the ones that legacy Named Credentials can use. The new Named Credentials cannot even do Basic Auth (although this can be worked around as we’ll discuss in a later post)