ExternalCredential | Metadata API Developer Guide

All credentials stored within this entity are encrypted under a framework that is consistent with other encryption frameworks on the platform. Salesforce encrypts your credentials by auto-creating org-specific keys. Credentials encrypted using the previous encryption scheme have been migrated to the new framework.

Note

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

ExternalCredential components have the suffix .externalCredential and are stored in the externalCredentials folder.

Version

ExternalCredential components are available in API version 56.0 and later.

Special Access Rules

There are no additional access requirements that are specific to this type.

Fields

Field Name	Description
authenticationProtocol	Field Type AuthenticationProtocol (enumeration of type string) Description Required. The authentication protocol that’s required to access the external system. Values are: `AwsSv4` `Custom` — User-created authentication. Specify the permission set, sequence number, and authentication parameters. Each authentication parameter requires a name and value. `Jwt` — Reserved for future use `JwtExchange` — Reserved for future use `NoAuthentication` —Reserved for future use `Oauth` `Password` — Reserved for future use For connections to Amazon Web Services using Signature Version 4, use `AwsSv4`. For connections using a direct token system, select `Jwt`. For Simple URL data sources, select `Custom` with no parameters. For cloud-based Files Connect external systems, select `Oauth`. For on-premises systems, select `Password`.
description	Field Type string Description A meaningful description of the external credential.
externalCredentialParameters	Field Type ExternalCredentialParameter[] Description One or more sets of parameters that further configure the external credential.
label	Field Type string Description Required. Name of the external credential.

ExternalCredentialParameter

Represents the parameters that configure an external credential. External credential parameters are used to configure external credential callouts through a combination of the type, name, and value/lookup fields. Available in API version 56.0 and later.

These parameters are used internally to provide a flexible architecture and are exposed here for packaging reasons.

Field Name	Description
authProvider	Field Type string Description Reference to an authentication provider that the AuthProvider component represents, which defines the service that provides the login process and approves access to the external system.
description	Field Type string Description A human readable description of this external credential parameter.
parameterName	Field Type string Description Required. The name of the external credential parameter.
parameterType	Field Type ExternalCredentialParamType (enumeration of type string) Description Required. The type of external credential parameter. The value of this field drives the behavior of the parameter. Values are: `AuthHeader`: Allows the user to specify custom authentication headers to be added to the callout at run time. When using `AuthHeader`, the parameterName field must be the header name as a string, and parameterValue must be a formula of a header value that is evaluated at run time. sequenceNumber determines the order in which headers are sent out in the callout. Headers with lower numbers are sent out first. `AuthParameter`: Allows users to add additional authentication settings. parameterName defines the parameter to set. For example, `AwsRegion` sets the AWS Region parameter to apply for an AWS Signature V4 authentication protocol and parameterValue is value for the AWS Region. `AuthProtocolVariant`: Used to specify a variant of an authentication protocol. For example, `Aws Sts` as a variant when the ParameterName is `AwsSv4` and the ParameterValue is `AwsSv4_STS`. `AuthProvider`: Specifies that this parameter configures an authentication provider referenced by the authProvider field. `AuthProviderUrlQueryParameter`: Allows the user to specify custom query parameters to be added to the callout to the authentication provider at run time. Currently, supported only for AWS Signature V4 with STS. The allowed `AuthProviderUrlQueryParameter` values are `AwsExternalId` and `AwsDuration`, used with AWS STS. `AwsStsPrincipal`: Configures AWS Signature V4 along with STS. parameterName is `AwsStsPrincipal` and parameterValue and principal aren’t specified. `NamedPrincipal`: Specifies that the parameter uses the same set of user credentials for all users who access the external system. Use the principal field to specify the permission set. `PerUserPrincipal`: Provides access control at the individual user level.
parameterValue	Field Type string Description If the parameterType field describes a literal value then the literal value is stored in this field.
principal	Field Type string Description If the value of the parameterType field is either `NamedPrincipal` or `PerUserPrincipal`, this field points to a permission set. That value then determines the set of users that are allowed to use credentials provided by the credential provider. The value of the parameterName field specifies the name of this principal.
sequenceNumber	Field Type int Description Specifies the order of principals to apply when a user participates in more than one principal. For example, a user could be part of multiple permission sets that are applicable for a credential provider. Priority is from lower to higher numbers. You can set this field only when parameterType is `NamedPrincipal`.

Declarative Metadata Sample Definition

The following is an example of an ExternalCredential component.

1<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
2    <label>SampleExternalCredential</label>
3    <authenticationProtocol>AwsSv4</authenticationProtocol>
4    <externalCredentialParameters>
5        <parameterName>Principal</parameterName>
6        <parameterType>NamedPrincipal</parameterType>
7        <principal>SamplePermissionSet</principal>
8        <sequenceNumber>1</sequenceNumber>
9    </externalCredentialParameters>
10    <externalCredentialParameters>
11        <parameterName>AwsService</parameterName>
12        <parameterValue>iam</parameterValue>
13        <parameterType>AuthParameter</parameterType>
14    </externalCredentialParameters>
15    <externalCredentialParameters>
16        <parameterName>AwsRegion</parameterName>
17        <parameterValue>us-east-1</parameterValue>
18        <parameterType>AuthParameter</parameterType>
19    </externalCredentialParameters>
20</ExternalCredential>

The following is an example package.xml that references the previous definition.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>ExternalCredential</name>
6    </types>
7    <version>56.0</version>
8</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.