The SAML assertion flow is an alternative for organizations that are currently using SAML to access Salesforce, and want to access the web services API the same way. The SAML assertion flow can only be used inside a single org. You don’t have to create a connected app to use this assertion flow.
Clients can use this assertion flow to federate with the API using a SAML assertion, in much the same way as they would federate with Salesforce for web single sign-on.
|Available in: Salesforce Classic|
|Available in: All Editions|
|To manage, create, edit, and delete OAuth applications:||“Manage Connected Apps”|
The SAML assertion flow isn’t supported for communities.
Configuring SAML for OAuth
To configure your organization to use SAML, follow the instructions in the Configuring SAML Settings for Single Sign-On topic. Once you have configured SAML, you can use the exact same configuration for both Web and API federation.
Two URLs are provided after you configure SAML for your organization:
- Salesforce.com Login URL—Use this URL when doing Web single sign-on.
- OAuth 2.0 Token Endpoint—Use this URL when exchanging a SAML assertion for an access token to be used with the API.
When generating SAML assertions to be used with the token endpoint, the recipient URL in the assertion can be the value from either 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 must obtain or generate a valid SAML response and POST it to the token endpoint. The method of obtaining this response is up to the client to determine. Once the client has a valid response, it sends the following parameters:
- grant_type—Value must be assertion for this flow.
- assertion—A Base-64 encoded, then URL encoded, SAML response that would normally be used for Web single sign-on.
- assertion_type—Must be urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser, URL encoded
- format—Expected return format. This parameter is optional. The default is json. Values are:
The following is the body of an example of an out-of-band POST made to the https://login.salesforce.com/services/oauth2/token
assertion=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHNhbW. . .
Salesforce Server Sends a Response
After the SAML response is verified, Salesforce sends a response to the client. The following parameters are in the body of the response:
- access_token—Salesforce session ID that can be used with the web services API.
- token_type—Value is Bearer for all responses that include an access token.
- id—Identity URL that can be used to both identify the user and query for more information about the user. See Identity URLs.
The following is an example response from Salesforce:
If an error occurs during this step, the response contains an error message with these parts:
- error—Error code
- error_description—Description of the error with additional information.
- unsupported_response_type—response type not supported
- invalid_request—HTTPS required
- invalid_request—must use HTTP POST
- invalid_assertion_type—specified assertion type is not supported
- invalid_grant—invalid authorization code (make sure that the client sends a URL encoded assertion and assertion_type)
- invalid_grant—IP restricted or invalid login hours
- inactive_user—user is inactive
- inactive_org—organization is locked, closed, or suspended
- rate_limit_exceeded—number of logins exceeded
- error_uri—A link to the SAML Assertion Validator, which contains more information about the failure. This is only returned when Salesforce is able to parse the assertion.
The following is an example error: