Few days ago I was lurking in the Named Credentials configurations.

What are named credentials?

Here are the official docs.

They are essentially a way to store callout configurations such as:

• Endpoint (only HTTPs endpoints are supported)
• Callout certificate (if needed, from the local key store)
• Authentication protocol (if needed)
• Authentication settings

With named credentials you don’t need Remote Site Setting configuration anymore: add you credential and the job is done!

The Endpoint stores the callout URL but it could also store a part of the endpoint (e.g. only the domain or a specific piece of path, such as https://na1.salesforce.com/services/Soap/class/).

The Callout certificate grabs a certificate from the Certificate and Key Management setup page, allowing a more secure connection between hosts.

I’m going to focus on the Authentication protocol.

You can choose among the following values:

• No Authentication
• Password authentication
• OAuth 2.0

And you can set the authentication globally (Identity type = Named principal) or per user (Identity Type = Per User): if you don’t need any authentication, just use the value “Identity Type = Anonymous”

The password authentication is pretty straightforward: it uses BASIC authentication (username/password BASE64 encoded sent in the request headers).

But what about OAuth2?

I wanted to test this option using all but the Salesforce platform: there are plenty of services that expose the OAuth 2.0 authentication, but I love Salesforce and that’s how I want to test things!

You need 2 orgs:

• Remote ORG: this will be the provider of your OAuth 2.0 authentication, it hosts the remote service you want to access (and that you can only access with this ORG’s user)
• Local ORG: this is the ORG where you want to invoke the remote service and where you are configuring the Named Credentials

Setup the Remote ORG

First let’s setup the remote service.

Create a new SOAP webservice:

global class EchoManager {
    webservice static String echo(String text){
        return 'ECHO FROM ORG '+UserInfo.getOrganizationId()+': '+text;
    } 
}

This service echoes the request text’s returning also the remote ORG ID.

Useful uh?

Go to Setup > Develop > Apex Classes search the EchoManager class and click the WSDL link next to the class name: this way you can download the WSDL file you are going to import in the Local ORG to call the service.

Make sure the remote user you’ll be using (with OAuth2) to consume the service from the Local ORG is enabled to access the Apex Class (from its Profile or assigning a Permission set: if this is an Administrator profile no need to check!).

Last step on this org is to setup a Connected App: this confgiuration will give access to the ORG from outside on behalf of an external application.

Go to Setup > Create > Apps, scroll to the Connected Apps section and click the New button:

Setup a name, a contact Email, a logo image (I choose Master Yoda).

Flag Enable OAuth Setting and set Callback URL to a fake value (e.g. callback://myapp): we’ll be configuring this field later (this hosts the callback url of the Local ORG).

Finally set the full and refresh_token scopes (the last one is necessary to allow for sending refresh token).

Onve you save it can take 5/10 minutes for the changes to be propagated.

This is pretty much what you see now (except for the Callback URL):

Let’s go back to the Local ORG.

Setup the Local ORG

First let’s import the remote service WSDL from Setup > Develop > Apex Classes and click the Generate From WSDL button.

Select the WSDL file just saved from the Remote ORG, use a namespace name (WSEchoManager in my case) and Salesforce will create the Apex Stub.

Let’s create a Visualforce page with a controller to test it:

public class EchoController {
    public String requestText{get;set;}
    public String responseText{get;set;}
    public void sendRequest(){
        this.responseText = null;
        try{
            WSEchoManager.EchoManager stub = new WSEchoManager.EchoManager();
            this.responseText = stub.echo(this.requestText);
        }catch(Exception e){
            this.responseText = 'Unexpected exception :'+e.getMessage();
        }
    }
}

<apex:page controller="EchoController" tabStyle="Account">
    <apex:sectionHeader title="Remote echoes" />
    <apex:form>
        <apex:pageBlock>
            <apex:pageBlockSection columns="2">
                <apex:pageBlockSectionItem>
                    <apex:outputLabel>Say something:</apex:outputLabel>
                    <apex:inputText value="{!requestText}" />
                </apex:pageBlockSectionItem>
                <apex:commandButton value="Send request" action="{!sendRequest}" />
            </apex:pageBlockSection>
            <apex:pageBlockSection columns="1" 
                                   title="Server response" 
                                   rendered="{!NOT(ISBLANK(responseText))}">
                <apex:outputText value="{!responseText}" />
            </apex:pageBlockSection>
        </apex:pageBlock>
    </apex:form>
</apex:page>

Let’s try it:

As expected we haven’t still enabled anything.

Jump to Setup > Security Controls > Auth. Providers and click the New button and choose the Salesforce provider type:

This is the authentication provider will be using to initiate the OAuth 2 dance with the Remote ORG.

In the Consumer Key and Consumer Secret fields set the values from the Remote ORG connected app (called Consumer Key and Secret as well).

The Authorization Endpoint URL and Token Endpoint URL are setup with the https://login.salesforce.com/services/oauth/… values, but in this case I’ve used the Remote ORG custom domain (you can leave with the default values).

In the Default Scopes set the selected scopes in the Remote ORG connected app separated by a blank space (full refresh_token).

Now click “Save” and get the Callback URL you get in the Salesforce Configuration section:

Go back to the Remote ORG connected app and set the Callback URL with the one just copied.

We are about there, don’t worry!

Go back to your Local ORG and go to Setup > Security Controls > Named Credentials and click New.

Give a fantastic name to your named credential (you’ll be using it in your stub class), set the URL with the service url you find in the WSEchoManager class:

 . . .
    public class EchoManager {
        public String endpoint_x = 'https://eu6.salesforce.com/services/Soap/class/EchoManager';
        public Map<String,String> inputHttpHeaders_x;
    . . .

Set the Named Principal Identity Type and the OAuth 2.0 protocol; select the Authentication Provider just configured and flag the Start Authentication Flow on Save: this way, upon saving the named credential, you are requested to access to the remote provider.

Flag Allow Merge Fields in HTTP Body as well in order to put the OAuth token inside the request in a “non standard” way (we dont’ want to use the Authorication: Bearer XXX header).

Cheers: you have a working connection!

Finally we have to change the stub code to recall the named credential:

 . . .
    public class EchoManager {
        public String endpoint_x = 'callout:Echo_Service';
        . . .
        public String echo(String text) {
            WSEchoManager.echo_element request_x = new WSEchoManager.echo_element();
            request_x.text = text;
            this.SessionHeader = new SessionHeader_element();
            this.SessionHeader.sessionId = '{!$Credential.OAuthToken}';
        . . .

We are using the Echo_Service named credential in the endpoint_x member and adding the SessionHeader parameters in the SOAP request using the named credential merge field {!$Credential.OAuthToken}, which stores the token needed to authorize the call.

Thanks to the Allow Merge Fields in HTTP Body the engine replaces automagically this string with the session ID referenced by the merge field inside the SOAP request…and:

You can find the full code in the following Github repository.