Loading
Salesforce now sends email only from verified domains. Read More
Identify Your Users and Manage Access
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
            SAML Assertion Flow for Accessing the API

            You are here:

            1. Salesforce Help
            2. Docs
            3. Identify Your Users and Manage Access

            SAML Assertion Flow for Accessing the API

            The SAML assertion flow is an alternative for orgs that use SAML to access Salesforce and want to access the API the same way. Clients can federate with the API using a SAML assertion, the same way they federate with Salesforce for Web Single Sign-On (Web SSO). You can use this assertion flow without a connected app.

            Required Editions

            Available in: both Salesforce Classic and Lightning Experience
            Available in: All Editions

            Review these limitations:

            • You can’t use this flow with more than one org.
            • Authentication through this flow doesn’t invoke login flows. You can’t apply login flows to API logins or to scenarios in which sessions pass to the UI through frontdoor.jsp from a non-UI login process.
            • Experience Cloud sites don’t support this flow.

            To use the SAML assertion flow, follow these steps.

            1. Configure SAML version 2.0 for your org.
            2. Exchange a SAML assertion for an access token.
            3. After verifying the assertion, Salesforce grants an access token.
            4. Use a JSON parser to process the response and extract the access token.
              Note
              Note A refresh_token is never issued in this flow.

            Configure SAML 2.0

            To configure your org to use SAML, see Configure SSO with Salesforce as a SAML Service Provider. You can use the same configuration for web and API federation.

            After you configure SAML, Salesforce generates these URLs.

            • Salesforce.com Login URL—Use this URL with Web SSO.
            • OAuth 2.0 Token Endpoint—Use this URL when exchanging a SAML assertion for an access token to access the API.

            When generating SAML assertions to use with the Salesforce token endpoint, the recipient URL in the assertion can be the value from the OAuth 2.0 Token Endpoint or the Salesforce.com Login URL.

            Exchange a SAML Assertion for an Access Token

            To exchange a SAML assertion for an access token, your client obtains or generates a valid SAML response, and then posts it to the Salesforce token endpoint. The client determines the method for obtaining this response.

            Here’s an example of an out-of-band POST made to the Salesforce token endpoint.

            grant_type=assertion&
assertion_type=urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser&
assertion=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHNhbW. . .

            When the client receives a valid response, it sends these parameters.

            Important
            Important When developing OAuth integrations, always pass sensitive information in the body of a POST request or in a request header. Don't use GET parameters in the URL query string to pass sensitive information. Sensitive information includes but isn't limited to usernames, passwords, OAuth tokens, client secrets, and any personally identifiable information. For more information on security best practices, see Storing Sensitive Data in the Secure Coding Guide.
            Parameter Description
            grant_type The OAuth 2.0 grant type that the connected app requests. The value must be this flow’s assertion.
            assertion A Base-64 encoded, then URL encoded, SAML response normally used for Web SSO.
            assertion_type The value must be urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser, URL encoded.
            format

            If not included in the request’s header, you can specify the expected return format. The format parameter takes precedence over the request’s header. These formats are supported.

            • urlencoded
            • json (default)
            • xml

            Salesforce Grants an Access Token

            After the SAML response is verified, Salesforce sends a response to the client containing the access token.

            Here’s an example response from Salesforce.

            {"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"instance_url":"https://yourInstance.salesforce.com",
"access_token":"00Dx0000000BV7z!AR8AQNhMmQeDIKR0.hZagSTaEPCkmoXeYnkaxQnqWlG6Sk9U3i3IFjEHIzDlsYdU0qoVCXNJtPOwdb7u5rKfq9NldfAKoQjd",
"token_type":"Bearer"}
            Parameter Description
            id An identity URL that can be used to identify the user and to query for more information about the user. See Identity URLs.
            instance_url A URL indicating the instance of the user’s org. For example: https://yourInstance.salesforce.com/.
            access_token OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. Additional permissions in the form of scopes can accompany the access token.
            token_type A Bearer token type, which is used for all responses that include an access token.

            See Also

             
            Loading
            Salesforce Help | Article