Authentication
Authentication
Every API call exposed through SDK require authenticated caller. Credentials are checked once with OAuth2(https://oauth.net/2/) and client is granted authentication token that must be passed with following calls to API.
SDK encapsulates authentication requests in Authenticator class and:
OAuthClientCredentials,
OAuthApplicationUserCredentials,
OAuthDeviceCredentials.
OAuth*Credentials classes are used to provide grant/flow specific credentials. Depending on credentials used to authenticate, generated token will be associated with different privileges. If multiple credentials are needed to support use case, appropriate token can be generated and regenerated before calls that require it.
Authentication steps
Authentication is a process where client will send correct credentials, for which server will return token that can be used to authorize further calls to API.
There are 4 steps necessary to acquire such token:
Create OAuth*Credentials instance for particular grant.
Create Authenticator instance passing it OAuth*Credentials instance generated in step 1.
Invoke getToken() method from Authenticator class
Result from step 3 is OAuth*Token instance, which contains more information about authentication token received from API like eg. how long token is active. In this step you must to call getAccessToken() method from returned OAuth*Token class instance
Save result from step 4 in ApiClient using setAccessToken(accessToken) method
Accepted Credentials
Authentication endpoint accepts 3 credential types (grants), each requiring different set of parameters. Below you can find lists of expected parameters when specific OAuth*Credentials is created.
OAuthClientCredentials class |
|||
Represents credentials required for client grant |
|||
field |
description |
type |
possible value |
clientId |
Client identifier |
String |
hexadecimal value or key |
clientSecret |
Client secret |
String |
hexadecimal value or key |
OAuthApplicationUserCredentials class |
|||
Represents credentials required for application grant |
|||
field |
description |
type |
possible value |
clientId |
Client identifier |
String |
hexadecimal value or key |
clientSecret |
Client secret |
String |
hexadecimal value or key |
username |
User identifier |
String |
|
password |
User password |
String |
|
device |
Identifier of device from which user is connecting |
String |
|
deviceName |
Name of device from which user is connecting |
String |
|
OAuthDeviceCredentials class |
|||
Represents credentials required for device grant |
|||
field |
description |
type |
possible value |
clientId |
Client identifier |
String |
hexadecimal value or key |
clientSecret |
Client secret |
String |
hexadecimal value or key |
uuid |
Unique, universal identifier of device |
String |
/vendor/unknown/cashier/dotnettest1 |
Received tokens
In Java SDK currently exist 3 types of tokens. Every token extends base class called AccessToken what means that when you'll create in the future new token type you also must extend this class.
Short introduction to existing token types in Java
Currently are implemented classes OAuthClientToken, OAuthApplicationUserToken and OAuthDeviceToken, which are a bit different what is shown below.
OAuthClientToken class has fields:
accessToken
tokenType
scope
OAuthApplicationUserToken class has fields:
accessToken
tokenType
scope
refreshToken
OAuthDeviceToken class has fields:
deviceCode
userCode
verificationUrl
interval
A base class for all above classes is AccessToken class, which has fields:
expiresIn
createdAt
Authentication token storage
In Java exists a cache solution using to store authentication token in cache. The cache solution consists of CacheItem abstract class with three important methods. If you would like to store authentication token in cache you must extend the CacheItem abstract class and then implement all their methods. By default SDK uses a file based cache to store tokens and implementation is made in FileCache class.
CacheItem abstract class methods
wasExpiring(AccessToken accessToken) - The method to check whether key isn't expired. Returns true or false.
set(String name, AccessToken accessToken) - The method to set authentication token as a cache item.
get(String name) - The method to get cache item for given name. Returns AccessToken class instance.
Authentication examples
Here are 3 code blocks examples. Only first code block example contains an explanation, because others examples are very similar to the first example and no needed to explain it.
Example for client credentials:
OAuthClientCredentials oAuthClientCredentials =
new
OAuthClientCredentials(
"..."
,
"..."
);
Authenticator authenticator =
new
Authenticator(oAuthClientCredentials);
OAuthClientToken accessToken = (OAuthClientToken) authenticator.getToken();
PaymentSecupayDebitsApi debitApi =
new
PaymentSecupayDebitsApi();
ApiClient debitApiClient = debitApi.getApiClient();
debitApiClient.setAccessToken(accessToken);
Explanation:
From line 1 to line 4 we pass clientId and clientSecret to OAuthClientCredentials constructor and we create a new object of this type
At line 5 we create Authenticator object providing it OAuth*Credentials object corresponding to grant required for particular API
At line 6 we call getToken() method from Authenticator and we save result in accessToken variable of type OAuthClientToken
At line 8 we create instance of specific API
At line 9 we get ApiClient object using getApiClient method from PaymentSecupayDebitsApi class
At line 10 we set accessToken to ApiClient
Example for application user credentials:
OAuthApplicationUserCredentials oAuthApplicationUserCredentials =
new
OAuthApplicationUserCredentials(
"..."
,
"..."
,
"..."
,
"..."
,
"..."
,
"..."
);
Authenticator authenticator =
new
Authenticator(oAuthApplicationUserCredentials);
OAuthApplicationUserToken accessToken = (OAuthApplicationUserToken) authenticator.getToken();
PaymentSecupayDebitsApi debitApi =
new
PaymentSecupayDebitsApi();
ApiClient debitApiClient = debitApi.getApiClient();
debitApiClient.setAccessToken(accessToken);
Example for device credentials:
OAuthDeviceCredentials oAuthDeviceCredentials =
new
OAuthDeviceCredentials(
"..."
,
"..."
,
"..."
);
Authenticator authenticator =
new
Authenticator(oAuthDeviceCredentials);
OAuthDeviceToken accessToken = (OAuthDeviceToken) authenticator.getToken();
PaymentSecupayDebitsApi debitApi =
new
PaymentSecupayDebitsApi();
ApiClient debitApiClient = debitApi.getApiClient();
debitApiClient.setAccessToken(accessToken);