ResourceFirst API: Method for Acquiring Token from SAML Authentication
In this document we use the software program curl to initiate a SAML session and end with a ResourceFirst API access_token. Similar tools such as PostMan can substitute for curl.
Overview
In this document we use the software program curl to initiate a SAML session and end with a ResourceFirst API access_token. Similar tools such as PostMan can substitute for curl.
curl enables us to interact with the SAML token authentication in the same ways a user’s browser would, including exchanging credentials with the IDP to receive a valid SAML ticket. The process begins with a ResourceFirst SP-Initiated redirect to the IDP. We end with a valid access_token.
Each step can be replicated in a browser, and the redirects observed through that browser’s tools. Issues in any one step can and should be observed to work in the browser first. This is especially true at the IDP authentication step. The required steps will vary with the IDP platform. Observing the IDP documentation or browser interaction is paramount.
ResourceFirst will request a SAML token, redirecting to the IDP. The IDP will authenticate the user credentials (the method is specific to the IDP platform). The SAMLResponse will be captured and handed off to ResourceFirst. This results in a cookie: AspNet.ExternalCookie. Follow up steps instruct the server to issue an AspNet.ApplicationCookie, which finally allows us to access the RF API’s /Token URI. This last step grants an access_token.
Note
We make use of curl’s -D flag to write the response headers to a filename (usually called simply header). We can then inspect the file for the redirection and cookie values to set in the following steps.
When a new cookie is created the cookie file must be updated. These lines are those that begin with set-cookie.
We omit code to extract the line from the header file and write to the cookie file. This can be done using any software programming or scripting method that fits your purposes.
Begin SP-Initiated IDP Request
ResourceFirst will initiate an IDP request when a user accesses the below URL
curl https://hostname/account/OWinSAMLAuthorize -D header
Contents of header will resemble the below:
HTTP/2 303
cache-control: private
location: https://idp.server/?SAMLRequest=xxxx…czrR6iiS_7B0Tm
server: Microsoft-IIS/10.0
x-aspnetmvc-version: 5.2
x-aspnet-version: 4.0.30319
set-cookie: Saml2.yzqr_2Du…
We save the set-cookie line to our cookie text file, and use the location line for our URI in the next step to begin the IDP authorization and SAML ticket acquisition.
Get SAML Token
Here the interaction will depend on your IDP. The exact steps are not documented here as each platform is different. Usually a form submission with user credentials is required.
A sample URI submission looks like
Request URL:
https://idp.server/?SAMLRequest=xxxx…Nd8tQm3W-wpnWZ
Note we pass the SAMLRequest and RelayState acquired in Step 1. The goal is to acquire a SAMLResponse value, and preserve our RelayState for future steps.
Provide SAML Response to ResourceFirst
Next we need our SAMLResponse and RelayState fields. They will be passed as a form back to ResourceFirst at the specific URI which handles the SAML verification.
Request URL:
curl -d “formText” -b cookie3 “https://hostname/Saml2/Acs” -D header
formText is the URL Encoded form, such as
RelayState=ZCUZ65VoLzrOFq5sSSp2FAFi&SAMLResponse=PHNhbWwycDp
You can also use the software PostMan :
Response cookie will have
set-cookie: Saml2.RPeRgKbIVjG8UY3FQI3SyO32=; path=/; expires=Thu, 01-Jan-1970 00:00:00 GMT
set-cookie: .AspNet.ExternalCookie=b634yz; path=/; secure; HttpOnly
The redirect tells us to use URI 
location: /Account/OWinSAMLAuthorizeCallback
Acquire ApplicationCookie
During the previous step the SAML ticket was authenticated and we have a cookie value of the form
set-cookie: .AspNet.ExternalCookie=x6m5mPnQnkHC…
This cookie allows ResourceFirst to verify your SAML claims.
Now we get an Application cookie.
Request URL: https://hostname/Account/OWinSAMLAuthorizeCallback
After populating the cookie file with
set-cookie: .AspNet.ExternalCookie=…
We access the URI with that cookie:
curl -D header -b cookie “https://hostname/Account/OWinSAMLAuthorizeCallback”
The file named “header” will contain entries such as
location: /Account/Authorize?client_id=self&redirect_uri=https%3A%2F%2Fhostname%2FSAML&scope=admin&response_type=token”
set-cookie: .AspNet.ApplicationCookie=4zI
We will use the value in location in the next curl call. Particularly the text after client_id. The cookie value is what we need to get the Token in the last step.
Get API Token
Now we ask the server to grant an API token.
Request URL: https://hostname/Account/Authorize
curl -D header -b cookie “https://hostname/Account/Authorize?c…nse_type=token”
The response header has the token. The result is:
HTTP/2 302
cache-control: private, s-maxage=0
pragma: no-cache
content-type: text/html; charset=utf-8
expires: -1
location: https://hostname/SAML#access_token=_…xpires_in=7200
The snippet with access_token is the Token for accessing the API.
