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.
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.
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.|
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 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.
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.