ExternalCredential

Represents the details of how Salesforce authenticates to the external system.

This type extends Metadata and inherits its fields.

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

Introduced in API version 56.0.

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

• Type: AuthenticationProtocol (enumeration of type string)

• Required: Yes

• Description: Required.

  The authentication protocol that’s required to access the external system.

  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.

• Possible values:

  • AwsSv4
  • Basic
  • 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

• Type: string
• Required: No
• Description: A meaningful description of the external credential.

• Type: ExternalCredentialParameter[]
• Required: No
• Description: One or more sets of parameters that further configure the external credential.

• Type: string

• Required: Yes

• Description: Required.

  Name of the external credential.

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 and lookup fields. These parameters are used internally to provide a flexible architecture and are exposed here for packaging reasons.

Introduced in API version 56.0.

• Type: string
• Required: No
• 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.

• Type: string
• Required: No
• Description: If the value of parameterType is SigningCertificate, then this field references the certificate.

• Type: string
• Required: No
• Description: A human-readable description of this external credential parameter.

• Type: string
• Required: No
• Description: Reference to an external authentication identity provider that the externalAuthIdentityProvider component represents. The externalAuthIdentityProvider defines the service that provides the login process and approves access to the external system.

• Type: string

• Required: No

• Description: Groups a parameter along with its respective principal. For example, with dynamic scopes, the user can apply a scope AuthParameter only when authenticated against a specific principal with a matching parameterGroup value.

  If a value for parameterGroup isn’t provided, parameterGroup defaults to the parameterName value for PER_USER and NAMED_PRINCIPAL. For all other parameters parameterGroup defaults to DEFAULT_GROUP.

• Type: string

• Required: Yes

• Description: Required.

  The name of the external credential parameter.

• Type: ExternalCredentialParamType (enumeration of type string)

• Required: Yes

• Description: Required.

  The type of external credential parameter. The value of this field drives the behavior of the parameter.

• Possible values:

  • AdditionalRefreshStatusCode — Allows the user to specify 4xx, 6xx, 7xx, 8xx, and 9xx HTTP status codes that trigger Salesforce to refresh expired or invalid access tokens, in addition to the standard 401 HTTP status code response.
  • 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 the user 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 the 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.
  • AuthProviderUrl — Specifies the authentication endpoint URL. For example, if the authentication type is OAuth with JWT Bearer Flow, then parameterValue is an authentication token endpoint.
  • 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 isn’t specified.
  • CreatedByNamespace — Reserved for internal use.
  • CustomPrincipal — Reserved for internal use.
  • ExternalAuthIdentityProvider — Specifies that this parameter configures an authentication provider referenced by the externalAuthIdentityProvider field.
  • GlobalNamedPrincipal — Reserved for internal use.
  • JwtBodyClaim — Specifies a JWT (JSON Web Token) body claim, where parameterName is the key and parameterValue is the value. For example, the parameter name for a JWT audience is aud.
  • JwtHeaderClaim — Specifies a JWT header claim, where parameterName is the key and parameterValue is the value. For example, the parameter name for a JWT key identifier is kid.
  • ManagedByComponent — Reserved for internal use.
  • ManagedByFeature — Reserved for internal use.
  • NamedPrincipal — Specifies that the parameter uses the same set of user credentials for all users who access the external system.
  • PerUserPrincipal — Provides access control at the individual user level.
  • PrincipalIdentityAlias — Reserved for internal use.
  • SfHttpRequestExtensionName — Reserved for internal use.
  • SigningCertificate — Specifies the certificate used for an authentication signature. Use the certificate field to specify the certificate name. Used for OAuth with JWT Bearer Flow and AwsSv4 STS with RolesAnywhere authentication.
  • SystemUserPrincipal — Reserved for internal use.

• Type: string
• Required: No
• Description: If the parameterType field describes a literal value then the literal value is stored in this field.

• Type: string
• Required: No
• 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.

• Type: int

• Required: No

• 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.

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        <sequenceNumber>1</sequenceNumber>
8    </externalCredentialParameters>
9    <externalCredentialParameters>
10        <parameterName>AwsService</parameterName>
11        <parameterValue>iam</parameterValue>
12        <parameterType>AuthParameter</parameterType>
13    </externalCredentialParameters>
14    <externalCredentialParameters>
15        <parameterName>AwsRegion</parameterName>
16        <parameterValue>us-east-1</parameterValue>
17        <parameterType>AuthParameter</parameterType>
18    </externalCredentialParameters>
19</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>

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.