Loading
Set Up and Maintain Your Salesforce Organization
Table of Contents
Filter by (0)Add
Select Filters

          No results
          No results
          Here are some search tips

          Check the spelling of your keywords.
          Use more general search terms.
          Select fewer filters to broaden your search.

            Search all of Salesforce Help
            Search all of Salesforce Help
            Define a Legacy Named Credential

            You are here:

            1. Salesforce Help
            2. Docs
            3. Set Up and Maintain Your Salesforce Organization

            Define a Legacy Named Credential

            Create a legacy named credential to specify the URL of a callout endpoint and its required authentication parameters in one definition. You can then specify the legacy named credential as a callout endpoint to let Salesforce handle all authentication. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the legacy named credential.

            Required Editions

            Available in: both Salesforce Classic and Lightning Experience
            Available in: All Editions
            User Permissions Needed
            To view legacy named credentials: View Setup and Configuration
            To create, edit, or delete legacy named credentials: Manage Named Credentials or Customize Applications
            Important
            Important In Winter ’23, Salesforce introduced an improved named credential that’s extensible, customizable, and more secure. We strongly recommend that you use this preferred credential instead of legacy named credentials, which are no longer updated or enhanced. For information on extensible, customizable named credentials, see Named Credentials Schema.

            Legacy named credentials are supported in these types of callout definitions:

            • Apex callouts
            • External data sources of these types:
              • Salesforce Connect: OData 2.0
              • Salesforce Connect: OData 4.0
              • Salesforce Connect: Custom (developed with the Apex Connector Framework)
              • Salesforce Connect: Amazon DynamoDB
            • External Services

            To set up a legacy named credential:

            1. From Setup, enter Named Credentials in the Quick Find box, then select Named Credentials.
            2. To create a legacy named credential, click New Legacy from the dropdown menu. To edit an existing legacy credential, click its link and click Edit.
            3. Enter information in the fields.
              FieldDescription
              Label

              A user-friendly name for the legacy named credential that’s displayed in the Salesforce user interface, such as in list views.

              If you set Identity Type to Per User, this label appears when your users view or edit their authentication settings for external systems.
              Name

              A unique identifier that’s used to refer to this legacy named credential from callout definitions and through the API.

              The name can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
              URL

              The URL or root URL of the callout endpoint. Must begin with http:// or https://. Can include a path but not a query string. Examples:

              • http://my_endpoint.example.com
              • https://my_endpoint.example.com/secure/payroll

              You can, however, append a query string and a specific path in the callout definition’s reference to the legacy named credential. For example, an Apex callout could reference the legacy named credential “My_Payroll_System” as follows.

              HttpRequest req = new HttpRequest();
req.setEndpoint('callout:My_Payroll_System/paystubs?format=json');
              Certificate

              If you specify a certificate, your Salesforce org supplies it when establishing each two-way SSL connection with the external system. The certificate is used for digital signatures, which verify that requests are coming from your Salesforce org.

              This certificate is for the callout endpoint URL. If you plan to use the JWT or JWT Token Exchange authentication protocol, enter the token endpoint URL certificate in the JWT Signing Certificate field. The JWT Signing Certificate field is displayed when you select JWT or JWT Token Exchange for the Authentication Protocol field, as described in a later step.
              Identity Type

              Determines whether you're using one set or multiple sets of credentials to access the external system.

              • Anonymous: No identity and therefore no authentication.
              • Per User: Use separate credentials for each user who accesses the external system via callouts. Select this option if the external system restricts access on a per-user basis.

                After you grant user access through permission sets or profiles in Salesforce, users can manage their own authentication settings for external systems in their personal settings. If you’re using JWT or JWT Token Exchange, the per-user credentials are handled for them.

              • Named Principal: Use the same set of credentials for all users who access the external system from your org. Select this option if you designate one user account on the external system for all your Salesforce org users.
            4. Select the authentication protocol.
              • If you select Password Authentication, enter the username and password for accessing the external system.
              • If you select OAuth 2.0, complete the following fields.
                FieldDescription
                Authentication Provider Choose the provider. See Authentication Providers.
                Scope

                Specifies the scope of permissions to request for the access token. Your authentication provider determines the allowed values. See Use the Scope Parameter.

                • The value that you enter replaces the Default Scopes value that’s defined in the specified authentication provider.
                • Whether scopes are defined can affect whether each OAuth flow prompts the user with a consent screen.
                • We recommend that you request a refresh token or offline access. Otherwise, when the token expires, you lose access to the external system.
                Start Authentication Flow on Save

                To authenticate to the external system and obtain an OAuth token, select this checkbox. This authentication process is called an OAuth flow.

                When you click Save, the external system prompts you to log in. After successful login, the external system grants you an OAuth token for accessing its data from this org.

                Redo the OAuth flow when you need a new token—for example, if the token expires—or if you edit the Scope or Authentication Provider fields. When the token expires, the external system returns a 401 HTTP error status.
              • If you select JWT or JWT Token Exchange, complete the following fields.
                FieldDescription
                Issuer Specify who issued the JWT using a case-sensitive string.
                Scope JWT Token Exchange only. Determines the permissions associated with the tokens that you’re requesting.
                Token Endpoint URL JWT Token Exchange only. The URL of the authorization provider. JSON Web Token requests are sent to the provider in exchange for access tokens.
                Per User Subject Per User identity type only. Formula string calculating the JWT’s subject. Include API names and constant strings in quotes. Allows a dynamic subject unique per user requesting the token. For example, 'User='+$User.Id.
                Named Principal Subject Named Principal identity type only. Enter static text, without quotes, that specifies the JWT subject.
                Audiences External service or other allowed recipients for the JWT. Store each audience as a case-sensitive string on a new line.
                Token Valid for The length of time that the token is valid to authenticate the user into the external system.
                JWT Signing Certificate Certificate verifying the JWT’s authenticity to external systems.
              • If you select AWS Signature Version 4, complete the following fields.
                FieldDescription
                AWS Access Key ID First part of the access key used to sign programmatic requests to AWS.
                AWS Secret Access Key Second part of the access key used to sign programmatic requests to AWS.
                AWS Region The AWS region name for the legacy named credential’s endpoint. For example, us-east-1.
                AWS Service The AWS utility to access.
            5. If you want to use custom headers or bodies in the callouts, enable the relevant options.
              FieldDescription
              Generate Authorization Header

              By default, Salesforce generates an authorization header and applies it to each callout that references the legacy named credential.

              Deselect this option only if one of the following statements applies.

              • The remote endpoint doesn’t support authorization headers.
              • The authorization headers are provided by other means. For example, in Apex callouts, the developer can have the code construct a custom authorization header for each callout.

              This option is required if you reference the legacy named credential from an external data source.

              Allow Merge Fields in HTTP Header

              Allow Merge Fields in HTTP Body

              In each Apex callout, the code specifies how the HTTP header and request body are constructed. For example, the Apex code can set the value of a cookie in an authorization header.

              These options enable the Apex code to use merge fields to populate the HTTP header and request body with org data when the callout is made.

              These options aren’t available if you reference the legacy named credential from an external data source.

            To reference a legacy named credential from a callout definition, use the legacy named credential URL. A legacy named credential URL contains the scheme callout:, the name of the legacy named credential, and an optional path. For example: callout:My_Named_Credential/some_path.

            You can append a query string to a legacy named credential URL. Use a question mark (?) as the separator between the legacy named credential URL and the query string. For example: callout:My_Named_Credential/some_path?format=json.

            See Also

             
            Loading
            Salesforce Help | Article