Skip to main content
PDWare Customer Success Center

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: 

https://hostname/Saml2/Acs

               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 :

clipboard_eaf856c43bc7cd8fc39d522de988f0fc5.png

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.

  • Was this article helpful?