---
schema_version: "1"
id: 98f89b606ced52faaf1f9ea70c8eb9afeb54700f3b9b7172a7fab10968a48c8d
title: Integrate a SAML SSO Service Provider as an External Client App
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/meta_external_client_app_saml.md
canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.meta_external_client_app_saml.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: e562b5a51df95fc888d374e9f4cb4fd57ea09b9358df635db19921c20b490d78
description: To use Salesforce as a SAML single sign-on (SSO) identity provider for a third-party service provider, integrate your service provider by using the external client apps framework. Create a SAML-enabled external client app and specify configuration information from your service provider. You can configure a SAML-enabled external client app via Metadata API only. External client apps with SAML configurations can’t be packaged or distributed.
products:
  - Security
  - Cross Cloud
release: "264"
---
# Integrate a SAML SSO Service Provider as an External Client App

To use Salesforce as a SAML single sign-on (SSO) identity provider for a third-party service provider, integrate your service provider by using the external client apps framework. Create a SAML-enabled external client app and specify configuration information from your service provider. You can configure a SAML-enabled external client app via Metadata API only. External client apps with SAML configurations can’t be packaged or distributed.

### Required Editions

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition"><colgroup><col></colgroup><tbody><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: <strong>Developer</strong>, <strong>Performance</strong>, and <strong>Unlimited</strong> Editions</td></tr></tbody></table>

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small permission">
        <colgroup>
          <col style="width:50%">
          <col style="width:50%">
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="colgroup" class="slds-cell-wrap" colspan="2" style="text-align:center;vertical-align:top;" id="d82527e43">User Permissions
              Needed</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="User Permissions Needed" class="slds-cell-wrap" style="vertical-align:top;" headers="d82527e43 ">To create and edit external client apps:</td>
            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d82527e43 ">Create, edit, and delete External Client Apps</td>
          </tr>
          <tr class="">
            <td data-label="User Permissions Needed" class="slds-cell-wrap" style="vertical-align:top;" headers="d82527e43 ">To edit external client app policies:</td>
            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d82527e43 ">View all External Client Apps, view their settings, and edit their
              policies</td>
          </tr>
        </tbody>
      </table>

Before you start, complete these steps.

- [Enable Salesforce as an identity provider](https://help.salesforce.com/s/articleView?id=xcloud.service_provider_prerequisites.htm&type=5&language=en_US).
- [Complete prerequisites for integrating service providers with SAML](https://help.salesforce.com/s/articleView?id=xcloud.service_provider_prerequisites.htm&type=5&language=en_US).
- [Enable external client apps in Setup](https://help.salesforce.com/s/articleView?id=sf.meta_set_up_external_client_apps_permissions.htm&language=en_US).
- [Configure a Salesforce DX project](https://help.salesforce.com/s/articleView?id=xcloud.configure_sfdx_for_external_client_apps.htm&type=5&language=en_US).

A SAML-enabled external client app consists of three main metadata components.

- A parent [ExternalClientApplication](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_externalclientapplication.htm) component
- An [ExtlClntAppConfigurablePolicies](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_extlclntappconfigurablepolicies.htm) component. This component is where you enable the SAML plugin for the app.
- An [ExtlClntAppSamlConfigurablePolicies](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_extlclntappsamlconfigurablepolicies.htm) component. This component contains SAML configuration information. Depending on your use case, it can also include an ExtlClntAppSamlConfigurablePoliciesAttribute subtype.

You can use any metadata deployment method that you prefer. These steps show you how to create and deploy these components by using [Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm).

## Create the Parent External Client App

To complete this step, see [Create a Local External Client App with Metadata API](https://help.salesforce.com/s/articleView?id=xcloud.meta_create_a_local_external_client_app.htm&type=5&language=en_US).

Because you can’t package an external client app with a SAML configuration, the distributionState must be set to `Local`. Here’s an example <external client app name>.eca-meta.xml file.

```markup
<?xml version="1.0" encoding="UTF-8"?>
<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
    <contactEmail>johndoe@example.com</contactEmail>
    <description>SAML external client app to integrate third-party service provider</description>
    <distributionState>Local</distributionState>
    <isProtected>false</isProtected>
    <label>mysamleca</label>
</ExternalClientApplication>
```

## Create the External Client App Policies Configuration

1. In your <project directory>/force-app/main/default/ directory, create a directory called extlClntAppPolicies.
2. In the extlClntAppPolicies, create a file called <ECA policy name>.ecaPlcy-meta.xml.
3. Configure the <ECA policy name>.ecaPlcy-meta.xml file with these fields.
    
     
    | Field | Description |
    | --- | --- |
    | externalClientApplication | The name of the parent external client app as specified in its label field. |
    | isEnabled | Defines whether the external client app can use plugins. Set this field to `true`. |
    | isOauthPluginEnabled | Defines whether the external client app can use the OAuth plugin. Because the isEnabled plugin automatically turns on all plugins and this app is only for SAML, set this field to `false`. |
    | isSamlPluginEnabled | Determines whether the external client app can use the SAML plugin. Set this field to `true`. |
    | label | The name for the configurable policies. |
    
    Here’s an example <ECA policy name>.ecaPlcy-meta.xml file.
    
    ```markup
    <?xml version="1.0" encoding="UTF-8"?>
           <ExtlClntAppConfigurablePolicies xmlns="http://soap.sforce.com/2006/04/metadata">
            <externalClientApplication>mysamleca</externalClientApplication>
            <isEnabled>true</isEnabled>
            <isSamlPluginEnabled>true</isSamlPluginEnabled>
            <isOauthPluginEnabled>false</isOauthPluginEnabled>
            <label>myecapolicy</label>
           </ExtlClntAppConfigurablePolicies>
    ```

## Create the External Client App SAML Policies Configuration

1. In your <project directory>/force-app/main/default/ directory, create a directory called extlClntAppSamlConfigurablePolicies.
2. In the extlClntAppSamlConfigurablePolicies, create a file called <ECA SAML policy name>.ecaSamlPlcy-meta.xml.
3. Configure the fields for the <ECA SAML policy name>.ecaSamlPlcy-meta.xml file.
    
    For detailed information about what fields to include, see the [ExtlClntAppSamlConfigurablePolicies metadata type](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_extlclntappsamlconfigurablepolicies.htm) in the Metadata API Reference Guide.
    
    Here’s an example <ECA SAML policy name>.ecaSamlPlcy-meta.xml file. This definition includes custom attributes, which are specified in the ExtlClntAppSamlConfigurablePoliciesAttribute subtypes.
    
    ```markup
    <?xml version="1.0" encoding="UTF-8"?>
    <ExtlClntAppSamlConfigurablePolicies xmlns="http://soap.sforce.com/2006/04/metadata">
        <acsUrl>https://www.<serviceprovideracsurl>.com</acsUrl>
        <entityUrl>https://www.<serviceproviderentityid>.com</entityUrl>
        <externalClientApplication>mysamleca</externalClientApplication>
        <issuer>https://mydomainname.my.salesforce.com</issuer>
        <label>myeca_samlpolicies</label>
        <nameIdFormat>Unspecified</nameIdFormat>
        <singleLogoutUrl>https://www.<serviceprovidersinglelogouturl>.com</singleLogoutUrl>
        <singleLogoutBindingType>RedirectBinding</singleLogoutBindingType>
        <subjectType>CustomAttribute</subjectType>
        <subjectCustomAttribute>MyCustomField</subjectCustomAttribute>
        <certificate>MIIDzDCCArQCCQCFaZKGsGqZ...</certificate>
        <encryptionCertificate>MIIDzDCCArQCCQCFaZKGsGqZ...</encryptionCertificate>
        <encryptionType>AES_128</encryptionType>
        <signingAlgorithmType>SHA1</signingAlgorithmType>
        <customAttributes>
            <key>User Firstname</key>
            <formula>$User.FirstName</formula>
        </customAttributes>
        <customAttributes>
            <key>User Country</key>
            <formula>$User.Country</formula>
        </customAttributes>
    </ExtlClntAppSamlConfigurablePolicies>
    ```

## Create the Package.xml File

Before you deploy the metadata components, bundle them together in a `package.xml` file.

1. In your <project directory>, create a file called package.xml. Don’t create a subfolder for this file. Here’s how the file structure looks.
    
    ![Visual Studio Code file explorer showing the location for the package.xml file in the project directory](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/identity/images/packagexml.png)
2. Add references to the ExternalClientApplication, ExtlClntAppConfigurablePolicies, and ExtlClntAppSamlConfigurablePolicies metadata types to the package.xml file.
    
    Here’s an example package.xml file.
    
    ```markup
    <?xml version="1.0" encoding="UTF-8"?>
    <Package xmlns="http://soap.sforce.com/2006/04/metadata">
        <types>
            <members>*</members>
            <name>ExternalClientApplication</name>
        </types>
        <types>
            <members>*</members>
            <name>ExtlClntAppConfigurablePolicies</name>
        </types>
        <types>
            <members>*</members>
            <name>ExtlClntAppSamlConfigurablePolicies</name>
        </types>
        <version>63.0</version>
    </Package>
    ```

## Deploy the SAML-Enabled External Client App

Push the changes from your local project directory to Salesforce.

1. Open a new Terminal window.
2. Go to the <project directory>.
3. To deploy the package.xml file, run this command.
    
    ```
    sf project deploy start --manifest package.xml -o <username@targetorg.com>
    ```
4. To verify that the metadata was deployed correctly, run this command.
    
    ```
    sf project retrieve start --source-dir force-app -o <username@targetorg.com>
    ```
    
    After the external client app is deployed, you can see it in the External Client App Manager in Setup. But you can’t view or edit its SAML configuration information from Setup.

To troubleshoot errors with deploying and retrieving metadata, see [Debug Errors When Deploying or Retrieving Source](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_trouble_temp_mdapi_dir.htm) in the Salesforce CLI Setup Guide.

After you deploy the SAML-enabled app and verify its information, complete your SSO setup with a final step: [Map Salesforce Users to the SAML Service Provider](https://help.salesforce.com/s/articleView?id=xcloud.service_provider_map_users.htm&type=5&language=en_US).

## Edit the SAML-Enabled External Client App

If necessary, make edits to your external client app SAML configuration.

1. Update the corresponding metadata component files in your <project directory>/force-app/main/default/ directory.
    - To update general information about the external client app, such as its description or contact email, edit the <external client app name>.eca-meta.xml file.
    - To update the external client app policies, such as the label for the policies component, edit the <ECA policy name>.ecaPlcy-meta.xml file.
    - To update the SAML configuration information, edit the <ECA SAML policy name>.ecaSamlPlcy-meta.xml file.
2. To push the changes to Salesforce, deploy the package.xml file again by running this command.
    
    ```
    sf project deploy start --manifest package.xml -o <username@targetorg.com>
    ```
    
    Complete this step even if you edit only one of the components. You can't deploy a single component.
3. To verify that the metadata was deployed correctly, run this command.
    
    ```
    sf project retrieve start --source-dir force-app -o <username@targetorg.com>
    ```