Populate External Credential Principals

Though named and external credentials are represented by metadata, the standard Metadata API can’t fully expose the definition of a credential and render sensitive information like tokens in plain text. This means that packaged credentials don’t include the access tokens or certificates that are needed for users to perform authenticated callouts.

After you install the managed package, you can use the UI or the Connect REST API to populate tokens or certificates in the external credential or its principals. These sections include the access details that you must populate based on your authentication protocol, as well as Connect REST API code samples. For more information about using the Connect REST API for named credentials, see Named Credentials Resources in the Connect REST API Developer Guide.

OAuth 2.0

After you install a package with a credential that uses an OAuth 2.0 authentication protocol, the steps that you must take depend on the OAuth 2.0 variant.

Browser Flow

External credentials that use the OAuth 2.0 authentication protocol with the Browser Flow variant reference an external auth identity provider.

After you install the package, you must create an authentication provider in the subscriber org. Then, use the Connect API or UI to assign the authentication provider to the installed external credential.

This code example uses a PUT request to add an authentication provider to the external credential.

1curl -X PUT https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/external-credentials/OAuthBrowserFlowExternalCredential -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@ec.json"

1{
2    "developerName": "OAuthBrowserFlowExternalCredential",
3    "masterLabel": "OAuthBrowserFlowExternalCredential",
4    "authenticationProtocol": "OAuth",
5    "parameters": [
6        {
7            "parameterName": "ExternalAuthIdentityProvider",
8            "parameterType": "ExternalAuthIdentityProvider",
9            "parameterValue": "externalIdp"
10        },
11        {
12            "parameterName": "Scope",
13            "parameterType": "AuthParameter",
14            "parameterValue": "some_access"
15        }
16    ],
17    "principals": [
18        {
19            "principalName": "NamedPrincipal",
20            "principalType": "NamedPrincipal",
21            "sequenceNumber": 1
22        },
23        {
24            "principalName": "PerUserPrincipal",
25            "principalType": "PerUserPrincipal",
26            "sequenceNumber": 2
27        }
28    ]
29}

JWT Bearer Flow

External credentials that use the OAuth 2.0 authentication protocol with the JWT Bearer Flow variant reference a signing certificate created in the subscriber org. After you install the package, you must create a signing certificate in the subscriber org. Then, use the Connect API or UI to assign the signing certificate to the installed external credential.

This code example uses a PUT request to add a signing certificate to the external credential.

1curl -X PUT https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/external-credentials/OAuthJwtBearerExternalCredential -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@ec.json"

1{
2    "developerName": "OAuthJwtBearerExternalCredential",
3    "masterLabel": "OAuthJwtBearerExternalCredential",
4    "authenticationProtocol": "OAuth",
5    "authenticationProtocolVariant": "JwtBearer",
6    "parameters": [
7        {
8            "parameterName": "SigningCertificate",
9            "parameterType": "SigningCertificate",
10            "parameterValue": "yourCert"
11        },
12        {
13            "parameterName": "iss",
14            "parameterType": "JwtBodyClaim",
15            "parameterValue": "iss"
16        },
17        {
18            "parameterName": "sub",
19            "parameterType": "JwtBodyClaim",
20            "parameterValue": "sub"
21        },
22        {
23            "parameterName": "aud",
24            "parameterType": "JwtBodyClaim",
25            "parameterValue": "aud"
26        },
27        {
28            "parameterName": "Scope",
29            "parameterType": "AuthParameter",
30            "parameterValue": "some_access"
31        },
32        {
33            "parameterName": "Identity Provider URL",
34            "parameterType": "AuthProviderUrl",
35            "parameterValue": "https://example.com/oauth/idp"
36        }
37    ],
38    "principals": [
39        {
40            "principalName": "NamedPrincipal",
41            "principalType": "NamedPrincipal",
42            "sequenceNumber": 1
43        },
44        {
45            "principalName": "PerUserPrincipal",
46            "principalType": "PerUserPrincipal",
47            "sequenceNumber": 2
48        }
49    ]
50}

Client Credentials with JWT Assertion

External credentials that use the OAuth 2.0 authentication protocol with the Client Credentials with JWT Assertion variant reference a client identifier as well as a signing certificate created in the subscriber org. After you install the package, you must assign a signing certificate to the external credential and populate the client ID.

This code example uses two Connect API requests: A PUT request to add a signing certificate to the external credential, and a POST request to populate the client ID.

First, add the signing certificate to the credential.

1curl -X PUT https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/external-credentials/OAuthClientCredentialsJwtAssertionExternalCredential -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@ec.json"

1{
2"developerName": "OAuthClientCredentialsJwtAssertionExternalCredential",
3    "masterLabel": "OAuthClientCredentialsJwtAssertionExternalCredential",
4    "authenticationProtocol": "OAuth",
5    "authenticationProtocolVariant": "ClientCredentialsJwtAssertion",
6    "parameters": [
7        {
8            "parameterName": "Scope",
9            "parameterType": "AuthParameter",
10            "parameterValue": "some_access"
11        },
12        {
13            "parameterName": "Identity Provider URL",
14            "parameterType": "AuthProviderUrl",
15            "parameterValue": "https://example.com/oauth/client-credentials"
16        },
17        {
18            "parameterName": "SigningCertificate",
19            "parameterType": "SigningCertificate",
20            "parameterValue": "yourCert"
21        },
22        {
23            "parameterName": "iss",
24            "parameterType": "JwtBodyClaim",
25            "parameterValue": "iss"
26        },
27        {
28            "parameterName": "sub",
29            "parameterType": "JwtBodyClaim",
30            "parameterValue": "sub"
31        },
32        {
33            "parameterName": "aud",
34            "parameterType": "JwtBodyClaim",
35            "parameterValue": "aud"
36        }
37    ],
38    "principals": [
39        {
40            "principalName": "NamedPrincipal",
41            "principalType": "NamedPrincipal",
42            "sequenceNumber": 1
43        }
44    ]
45}

Next, populate the client ID.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "OAuthClientCredentialsJwtAssertionExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "clientId": {
7            "value": "your-client-id",
8            "encrypted": false
9        }
10    }
11}

Client Credentials with Client Secret Flow

External credentials that use the OAuth 2.0 authentication protocol with the Client Credentials with Client Secret Flow variant include a client identifier and client secret. After you install the package, you must populate the client ID and client secret.

This code example uses a POST request to populate the client ID and client secret.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "OAuthClientCredentialsClientSecretExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "clientId": {
7            "value": "your-client-id",
8            "encrypted": false
9        },
10        "clientSecret": {
11            "value": "your-client-secret",
12            "encrypted": true
13        }
14    }
15}

AWS Signature v4

After you install a package with a credential that uses an AWS Signature v4 authentication protocol, the steps that you must take depend on the protocol’s variant.

Standard AWS Signature v4

External credentials that use the standard AWS Signature v4 variant use an access key and secret to authenticate. After you install the package, you must populate the access key and secret.

This code example uses a POST request to populate the access key and secret.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "AwsSv4ExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "awsAccessKeyId": {
7            "value": "accessKey",
8            "encrypted": false
9        },
10        "awsSecretAccessKey": {
11            "value": "accessSecret",
12            "encrypted": true
13        }
14    }
15}

AWS Signature v4 with STS Principal

External credentials that use the AWS STS variant with the STS principal type use a long-term access key and secret to authenticate. After you install the package, you must populate the access key and secret.

This code example uses a POST request to populate the access key and secret.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "AwsSv4StsExternalCredential",
3    "principalName": "AwsStsPrincipal",
4    "principalType": "AwsStsPrincipal",
5    "credentials": {
6        "awsAccessKeyId": {
7            "value": "accessKey",
8            "encrypted": false
9        },
10        "awsSecretAccessKey": {
11            "value": "accessSecret",
12            "encrypted": true
13        }
14    }
15}

AWS Signature v4 with STS Named Principal

External credentials that use the AWS STS variant with the named principal type use a Role Amazon Resource Name (ARN) certificate to authenticate. After you install the package, you must populate the role ARN certificate.

This code example uses a POST request to populate the role ARN certificate.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "AwsSv4StsExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "awsRoleArn": {
7            "value": "arn:aws:iam::1234567890:yourRole/",
8            "encrypted": false
9        }
10    }
11}

AWS STS Roles Anywhere

External credentials that use the AWS STS Roles Anywhere variant use a certificate to request temporary, limited-privilege credentials controlled via IAM policies and roles. After you install the package, you must populate the role ARN certificate.

This code example uses a POST request to populate the role ARN certificate.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "AwsSv4StsRolesAnywhereExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "awsRoleArn": {
7            "value": "arn:aws:iam::1234567890:yourRole/",
8            "encrypted": false
9        }
10    }
11}

Custom

With the Custom authentication protocol, each user implements custom credentials. Nothing is required after you install the package, but you can use a POST request to populate custom user-specified credentials.

This code example uses a POST request to populate an API key.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "CustomExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "customCredentialName": {
7            "value": "customCredentialValue",
8            "encrypted": false
9        },
10        "yourApiKeyHeaderNameHere": {
11            "value": "yourApiKeyValue",
12            "encrypted": true
13        }
14    }
15}

JWT

External credentials that use the JWT authentication protocol reference a signing certificate created in the subscriber org. After you install the package, you must create a signing certificate in the subscriber org. Then, use the Connect API or UI to assign the signing certificate to the installed external credential.

This code example uses a PUT request to add a signing certificate to the external credential.

1curl -X PUT https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/external-credentials/JwtExternalCredential -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@ec.json"

1{
2    "developerName": "JwtExternalCredential",
3    "masterLabel": "JwtExternalCredential",
4    "authenticationProtocol": "Jwt",
5    "parameters": [
6        {
7            "parameterName": "SigningCertificate",
8            "parameterType": "SigningCertificate",
9            "parameterValue": "yourCert"
10        },
11        {
12            "parameterName": "iss",
13            "parameterType": "JwtBodyClaim",
14            "parameterValue": "iss"
15        },
16        {
17            "parameterName": "sub",
18            "parameterType": "JwtBodyClaim",
19            "parameterValue": "sub"
20        },
21        {
22            "parameterName": "aud",
23            "parameterType": "JwtBodyClaim",
24            "parameterValue": "echo"
25        }
26    ],
27    "principals": [
28        {
29            "principalName": "NamedPrincipal",
30            "principalType": "NamedPrincipal",
31            "sequenceNumber": 1
32        },
33        {
34            "principalName": "PerUserPrincipal",
35            "principalType": "PerUserPrincipal",
36            "sequenceNumber": 2
37        }
38    ]
39}

Basic

External credentials that use the Basic authentication protocol authenticate with a static username and password. Basic authentication supports two identity types:

Named Principal: A Salesforce admin uses one username and password to authenticate into the external system on behalf of all users.
Per User Principal: Each user accessing the external system manages their own username and password.

After you install a credential that uses Basic authentication, you must populate the username and password.

Named Principal

This code example uses a POST request to populate a named principal username and password.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "BasicExternalCredential",
3    "principalName": "NamedPrincipal",
4    "principalType": "NamedPrincipal",
5    "credentials": {
6        "username": {
7            "value": "you@example.com",
8            "encrypted": false
9        },
10        "password": {
11            "value": "test1234",
12            "encrypted": true
13        }
14    }
15}

Per User Principal

This code example uses a POST request to populate a per-user principal username and password.

1curl -X POST https://MyDomainName.my.salesforce.com/services/data/v60.0/named-credentials/credential/ -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@credentials.json"

1{
2    "externalCredential": "BasicExternalCredential",
3    "principalName": "PerUserPrincipal",
4    "principalType": "PerUserPrincipal",
5    "credentials": {
6        "username": {
7            "value": "you@example.com",
8            "encrypted": false
9        },
10        "password": {
11            "value": "test1234",
12            "encrypted": true
13        }
14    }
15}