Implementation, Preparing the Application to Transact: Sign-On Authentication

Step 1: Sign-On Authentication

CWS implementations support Security Assertion Markup Language (SAML) token authentication credentials. SAML is dealt with behind the scenes and should not require in-depth expertise by the application developer.

For more information, refer to http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language.

Note: Future releases of CWS will support username/password authentication credentials.

The following operations are used to facilitate application sign-on authentication for both SOAP and REST implementations:

Sign-On Authentication Operations

SignOnWithToken (SOAP)

SignOn (REST)

Important! All parameters in each operation are considered "required" unless otherwise noted.

 


 

SignOnWithToken (SOAP)/SignOn (REST)

The SignOnWithToken/SignOn operations facilitate the authentication of identity tokens and the issuance of session tokens during application sign-on.

Note: When implementing token-based authentication, the SignOnWithToken/SignOn operations must be invoked before all other operations to retrieve a session token, which is required in all subsequent transaction processing requests.

SOAP

Operation

string SignOnWithToken(string identityToken);

Parameters

Parameter Data Type Description
identityToken String The identity token provisioned during the merchant/software company activation process.

Return Type

Data Type Description
string The short-lived sessionToken.

Note: This token will expire every 30 minutes. Transaction Processing operations attempted with an expired sessionToken will result in an ExpiredTokenFault. To refresh the sessionToken, re-invoke SignOnWithToken.

Exceptions

CWSFault AuthenticationFault
ExpiredTokenFault STSUnavailableFault
InvalidTokenFault   

For additional details about each fault, refer to Service Information Faults in the CWS Developer API Reference.

public function signOn()
{
	if ($this->session_token == '')
	{
		try
		{
			$st = new SignOnWithToken ();
			$st->identityToken = $this->token->identityToken;
			$response = $this->serviceInfo->SignOnWithToken ( $st );
			$this->session_token = $response->SignOnWithTokenResult;
		}
		catch ( Exception $e )
		{
			echo '
SERVER ERROR: Error Signing On.
'; echo $this->serviceInfo->__getLastRequestHeaders(); echo $this->serviceInfo->__getLastRequest(); echo 'REQUEST
' . $this->serviceInfo->__getLastRequest (); $xmlFault = $this->serviceInfo->__getLastResponse (); $errors = handleSvcInfoFault ( $e, $xmlFault ); echo $errors; exit (); } } return true; }
public string SignOn(string identityToken = null)
{
	using (var client = new CWSServiceInformationClient(ConfigurationManager.AppSettings["Bindings.StsSoap"]))
	{
		try
		{
			return client.SignOnWithToken(_identityToken);
		}
		catch (FaultException ex)
		{
			SoapFaultHandler.HandleFaultException(ex);
		}
	}
}

REST

Note: The HTTP Authorization Header must contain the identityToken value.

Operation

URL https://api.nabcommerce.com/REST/2.0.18/SvcInfo/token
Action GET

Parameters

None.

Message Body Type

None.

Return Type

Data Type Description
string The short-lived sessionToken.

Note:This token will expire every 30 minutes. Transaction Processing operations attempted with an expired sessionToken will result in an ExpiredTokenFault. To refresh the sessionToken, re-invoke SignOn.

Exceptions

CWSFault AuthenticationFault
ExpiredTokenFault STSUnavailableFault
InvalidTokenFault   

For additional details about each fault, refer to Service Information Faults in the CWS Developer API Reference.

public function signOn()
{
	if ($this->session_token == '')
	{
		$msgBody = '';
		$url = $this->svcInfo.'/token';
		$action = 'GET'; // HttpMethod::Get
		$response = curl_json($msgBody, $url, $action, $this->token->identityToken);
		if(isset($response->body->ErrorId))
		{
			handleRestFault($response);
			return false;
		}
		if(isset($response[2]))
		{
			$body = $response[2];
			$info = $response[1];
		}
		else return false;
		//Currently the session token does not have any slashes that would be escaped to \/.
		//This is safe as the generated saml is functionally confined to the ASCII character set.
		$this->session_token= trim($body, "\"");
	}
	return true;
}
public string SignOn(string identityToken = null)
{
	var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
	// No body is required for SignOn in the HttpWebRequest.
	var requestString = RestBaseUri + "/token";
 
	HttpWebRequest request = WebRequest.Create(requestString) as HttpWebRequest;
	request.Method = HttpMethod.GET.ToString();
	request.Credentials = new NetworkCredential(_identityToken, "");
 
	request.ContentType = isJson ? "application/json" : "application/xml";
 
	try
	{
		return RestHelper.GetResponse(request, isJson);
	}
	catch (Exception ex)
	{
		RestFaultHandler.HandleFaultException(ex, isJson);
	}
}

 

Comments