Sign-On Authentication

During the merchant activation process, transaction originators are issued a Service Key and credentials for authentication. At runtime, the payment application uses the credentials to authenticate to CWS. Only token-based authentication credentials are supported.

Note: A future release of CWS may support username/password authentication credentials.

CWS utilizes two types of Security Assertion Markup Language (SAML) authentication tokens: Identity Tokens & Session Tokens.

Identity Token

identityToken is a signed authentication token given to merchants or other transaction originators to prevent the unauthorized use of an application. Identity tokens expire after 3 years and require renewal. Authentication credentials are used to authenticate to CWS by invoking the Service Information SignOnWithToken/SignOn operation and passing a valid identityToken. After successful authentication, a sessionToken is returned for use in all subsequent Service Information and Transaction Processing operations.

Securing Identity Tokens

Identity tokens can be stored and secured in a file or database. Depending on the storage method selected, access control and encryption considerations dependent upon the application environment are described below.

Storage Mechanism	Access Control Method	Encryption (Recommended)
File	File System Permissions	Whole disk encryption, file-based encryption, or application-specific encryption such as Hardware Security Modules (HSM) to securely store and access identity tokens.
Database	Database User Permissions	Entire database encryption, single column encryption, or application-specific encryption.

IMPORTANT! If you plan to store the identity token string in a file, you are required to secure it using read-only file system permissions based on the active user account. This applies to third-party applications requiring installation and configuration on the application user’s desktop. Applying encryption on the entire file system or implement file-based or application-specific encryption depend on the requirements of the application.

Best practices related to file system-based security of identity tokens include:

Set file permissions so only Authorized Administrative Users or Currently Active Service User Account can read or write to the file storing the identity token.
Ensure only authorized administrator users of the application can call operations to read or write to the file storing the identity token.
Ensure IT policies and procedures are in place to enforce and monitor the protection of the file storing the identity token.
Document (and train if applicable) any customers on the policies and procedures for operating, managing, deploying or otherwise have access to machines storing identity tokens to protect the tokens.
Notifying EVO Snap* Support immediately if you believe an identity token has been compromised.

One other option for securing an identity token is to encrypt and store the identity token string in a database. This may be beneficial when the application resides in an environment where access is provided via a hosted web solution. Contact EVO Snap* Support to determining which method is the most appropriate for your specific solution.

Session Tokens

A Session token (sessionToken) ia a ‘limited-life’ token used to authenticate to CWS when invoking all Service Information and Transaction Processing operations after sign-on.

Session tokens expire 30 minutes after creation and should only be stored in memory or cache for the life of the session or until expiration. When an expired session token is used to invoke an operation, CWS returns an ExpiredTokenFault, at which time the application should re-invoke the SignOnWithToken/SignOn operation and pass a valid identityToken to retrieve a new session token.

Note: Applications should only request a new session token upon expiration of a previous session token. Requesting a new session token for every transaction will lead to processing delays in high transaction volume applications. As a best practice, the application should renew its session token only if older than 25 minutes. The application should also have fault handling to perform a refresh if an ‘ExpiredTokenFault’ is received.

The authentication process:

During the merchant activation process, the merchant is assigned an identity token. The identity token is provided to the application administrator and embedded into the application for use during application sign-on authentication. The SignOnWithToken/SignOn operation is invoked during initial application sign-on to validate the identity token established during the merchant activation process. Once the identity token is validated by the Token Service, a session token is returned to the application.