Synchronous authentication is the simplest authentication mode available. When adding account, used has to provide all Required-client-attributes which then are submitted to adapter. In most cases adapter will verify provided credentials against external system it integrates with. In response adapter sends back the AuthenticationResponse with an appropriate status (Success or Failure).

AuthenticationResponse

AuthenticationResponse can represent a successful or failed authentication.

Success

In case of success, response can contain additional data related to authenticated account:

AccountSpecificListOfValuesMap

Allows to define account specific list of values which can be used with listOfValuesDependsOnAttribute enabled attributes.

Structure of AccountSpecificListOfValuesMap is as follows:

AuthenticationResponse response = AuthenticationResponseBuilder.success()
        .withAccountSpecificListOfValues("LOCATION_ATTRIBUTE", List.of("12345678901234", "12345678901235"))
                .withAccountSpecificListOfValues("BRAND_ATTRIBUTE", List.of("ACME", "DEMO"))
                        .build();

"accountSpecificListOfValuesMap" : {
      "LOCATION_ATTRIBUTE" : {
                "defaultAccount" : [ "12345678901234", "12345678901235" ]
                    },
                        "BRAND_ATTRIBUTE" : {
                                  "defaultAccount" : [ "ACME", "DEMO" ]
                                      }
                                      }

📘

Although it is technically possible to return values for different account that currently authenticated one, SDK doesn’t allow for this and will automatically assign account to the list of attribute-values pairs.

Provided values will overwrite existing values in PDX Core.

Remember that LOCATION_ATTRIBUTE and BRAND_ATTRIBUTE attributes should be defined in datastandard.

ClientSpecificListOfValuesMap

Similar to AccountSpecificListOfValuesMap, ClientSpecificListOfValuesMap allows adapter to define client specific values, but this time independent of account.

Structure of ClientSpecificListOfValuesMap is as follows:

AuthenticationResponse response = AuthenticationResponseBuilder.success()
        .withClientSpecificListOfValues("supplierIdList", List.of("12345678901234", "12345678901235"))
                .withClientSpecificListOfValues("brands", List.of("ACME", "DEMO"))
                        .build();

"clientSpecificListOfValuesMap" : {
      "brands" : [ "ACME", "DEMO" ],
          "supplierIdList" : [ "12345678901234", "12345678901235" ]
          }

📘

Note that map key is not the id of an attribute but the list of values name used in clientSpecificListOfValues definition.

Failure

Examples of failure responses:

In case of failure, response should contain erroneousProperties ids or errorTranslationKeys used to give user a feedback on what is the cause of the failure.

erroneousProperties should match provided Required-client-attributes .

Currently available errorTranslationKeys are:

"SUPPLIER_USER_GROUP_MISSING": "Supplier id is missing for given credentials",
"INVALID_SUBSCRIPTION_ID": "Subscription ID is not valid, value must be an integer.",
"INVALID_SUBSCRIPTION_CODE": "Subscription Code is not valid, value must start with O or A, then be followed by 3 uppercase alphanumeric characters, followed by 3 integers.",
"DUPLICATE_VENDOR_ID": "This vendor had already been added to this channel. Please configure another Vendor Identifier and try again.",
"COMMUNICATION_ERROR": "A communication error occurred while attempting to contact external system.",
"UNKNOWN_ERROR": "Unknown error occurred while attempting to contact external system."

When using SDK, all possible values are available in AuthenticationResponseBuilder.ErrorTranslationKey enum.

Example of failure responses:

AuthenticationResponse internalResponse = AuthenticationResponseBuilder.failure().build();

{
    "status" : "Failure",
    "errorTranslationKeys" : [ "UNKNOWN_ERROR" ]
}

📘

Notice that if no erroneousProperties nor errorTranslationKeys are provided, UNKNOWN_ERROR will be returned.

AuthenticationResponse internalResponse = AuthenticationResponseBuilder.failure()
        .withErroneousProperties(List.of("login", "password"))
        .withErrorTranslationKeys(List.of(ErrorTranslationKey.DUPLICATE_VENDOR_ID, ErrorTranslationKey.INVALID_SUBSCRIPTION_ID))
        .build();

{
    "status" : "Failure",
    "erroneousProperties" : [ "login", "password" ],
    "errorTranslationKeys" : [ "DUPLICATE_VENDOR_ID", "INVALID_SUBSCRIPTION_ID" ]
}