SAML Protocol for the REST API
All clients follow a basic message flow to access the REST API using SAML. Whereas CSM acts as both the service provider and the identity provider in OAuth2 protocol, SAML protocol introduces a third-party identity provider.
For information about supported identity providers and the configuration procedure, see Configure the SAML Identity Provider
When a User navigates to the REST API, CSM redirects the User agent to the single sign-on service at the User's identity provider where the User enters his credentials. The User's identity is authenticated by the identity provider. If the authentication is successful, the identity provider returns a SAML assertion to CSM. The assertion indicates that a trusted identity provider successfully authenticated the User so that CSM can proceed to grant access to the REST API. CSM parses the assertion and returns the assertion data to the User agent. The User agent uses the assertion data to make a request to the token operation, and passes data in the request body as shown:
| Parameter | Value |
|---|---|
| grant_type | password |
| client_id | as usual |
| username | e-mail address |
| password | parsed SAML ticket |
| auth_mode | SAML |
If the request is successful, CSM returns an access token to the User agent. The access token allows the User agent to access the REST API as long as the token remains valid. The following diagram shows the basic SAML message flow:
SAML Protocol Using a Final URI Query String
You may optionally use a final URI query string to pass form data to token requests. Example:
saml/login.cshtml?finalUri=http://localhost/SamlSampleBrowserApp/default.aspx?testQueryParameter=myValueForMySystem
After the SAML assertion is parsed, a web form is returned with an auto-submit method on the body of the form. The method posts form data to the requested final URI. Example:
<html><body onload='document.forms[""samlResult""].submit()'><form name='samlResult' action='{finalUri}' method='post'><input type='hidden' name='userId' value='{nameId}'><input type='hidden' name='nameQualifier' value='{nameQualifier}'><input type='hidden' name='ticket' value='{ticket}'><input type='hidden' name='result' value='ok'><input type='hidden' name='statusCode' value='{statusCode}'><input type='hidden' name='statusMessage' value='{statusMessage}'></form></body></html>
The following diagram shows the SAML message flow with a final URI:
