Authentication and authorization


Whether you are building a website, a cashier system or a point-of-sale device, all functionality starts with a connection to Secucard's services. Authorization for these services is done using OAuth2, which is an open authorization standard. Authorization basically means that you need to be permitted (authorized) to use a specific service. In order for us to know whether you are permitted to do so, we first need to know who you are, which is the process of authentication. A more elaborate description of the differences between authentication and authorization can be found here.

When you have authenticated yourself or your device, you receive a security token (access token), which is everything you need to authorize yourself for all services. This access token is sent with nearly all API server requests, to confirm that this request was made from an authorized source. These access tokens are valid for a limited time, generally 20 minutes. It is therefore advisable to store this token and reuse it for all API server requests for as long as the token is valid. This avoids frequent authentication, which would cost you server round-trips for no reason.

Apart from receiving an access token after successfully authenticating, you also receive a refresh token. Where you use the access token to prove who you are to the API, the refresh token is used to obtain a new access token when the current access token has expired. After refreshing, you will continue to use the newly obtained access token for further use of the API.

The client SDK takes care of these details for you. The two things you need to provide the client are:

  • Credentials, either statically in the client configuration or at run-time through a special credential callback provided to the client. The latter is especially useful when using the client in a mobile application, where the user is asked for credentials. You obviously do not want to store this information in the client configuration.

  • Storage interface, which is used by the client to persist information like the security token mentioned earlier. The user needs full control over this interface, which can be as simple as an in-memory dictionary object. The client will always check the storage interface for a security token first, so clearing the storage interface implicitly causes the client to re-authenticate and obtain a new security token.

There are two types of authentication, namely user credentials authentication and two-way authentication. The former is typically used for server-to-server communication, whereas the latter is intended to be used for cashier applications and point-of-sale devices.

User credentials authentication

When you run a website with online payment possiblilities, you authenticate yourself using your client identifier and client secret, which you receive from us. When the client identifier you provided is intended to be used for this type of authorization and the client secret matches the client identifier, you receive a refresh token from the authentication service. If this is not the case, you receive an error providing an exact description of the problem.

User credential authentication

Two-way authentication

In case you are developing a cashier application or a point-of-sale device (POS), two-way authentication is necessary. This means that you provide your client identifier and client secret with your applications or devices. You also provide a means of uniquely identifying your device, using key/value pairs. These key/value pairs together form the unique device identifier, or UUID. An example of such UUID is: /vendor/mycompany/serial/1234.

The end user then connects the application or device to our server, authenticates it using the information provided by you and receives a verification code and verification URL. The end user then visits the verification URL, selects the intended device and enters that verification code. The client periodically checks with the server whether the user has verified the decive, and receives a refresh token as soon as this is the case.

Device authentication

Now you know about authentication, it is time to start connecting to our servers and use our services. Refer to SecucardConnect class to learn about the one class you need to instantiate in order to use these services.