Authentication Use Cases

The use cases related to creation of authentication codes and data signing.

Validate the Authentication Code

Use this method to send authenticated GET or POST requests to given URL with provided data.

java -jar powerauth-java-cmd.jar \
    --url "http://localhost:8080/enrollment-server/pa/v4/auth/validate" \
    --status-file "/tmp/pa_status.json" \
    --config-file "/tmp/pamk.json" \
    --method "authenticate" \
    --http-method "POST" \
    --resource-id "/pa/auth/validate" \
    --auth-code-type "possession_knowledge" \
    --data-file "/tmp/request.json" \
    --version "4.0" \
    --password "1234"

Uses the authenticate method to compute an authentication code for given data using an activation record associated with an activation ID stored in the status file /tmp/pa_status.json. Calls an authenticated endpoint http://localhost:8080/enrollment-server/pa/v4/auth/validate that is identified by an identifier /pa/auth/validate (by convention the same as the endpoint name after the main context except the version). The endpoint must be published by the application, see Verify Authentication. Uses the master public key and application identifiers stored in the /tmp/pamk.json file. Uses HTTP method POST, possession_knowledge authentication code type and takes the request data from a file /tmp/request.json. Unlocks the knowledge-related authentication key using 1234 as a password.

Note: If a --password option is not provided, this method requires interactive console input of the password, in order to unlock the knowledge-related authentication key.

In case you are validating authentication code on requests that require authenticated session, use --http-header option:

You can use the dry-run parameter, in this case the step is stopped right after authenticating the request body and preparing appropriate headers.

java -jar powerauth-java-cmd.jar \
    --url "http://localhost:8080/enrollment-server/pa/v4/auth/validate" \
    --status-file "/tmp/pa_status.json" \
    --config-file "/tmp/pamk.json" \
    --method "authenticate" \
    --http-method "POST" \
    --http-header Cookie="JSESSIONID=D0A047F9E8A9928386A5B34AB6343C30"
    --resource-id "/pa/auth/validate" \
    --auth-code-type "possession_knowledge" \
    --data-file "/tmp/request.json" \
    --version "4.0" \
    --password "1234"

Compute Offline Authentication Code

Use this method to compute offline PowerAuth authentication code.

java -jar powerauth-java-cmd.jar \
    --status-file "/tmp/pa_status.json" \
    --config-file "/tmp/pamk.json" \
    --method "compute-offline-auth-code" \
    --qr-code-data "A2\n4bG7ZvoG6UfkF29iwfWXiA==\n2WVNRWpbnQOmzVwWwBe8bMsQIs8zKiy/oRYH7TOFE2lQ=" \
    --version "4.0" \
    --password "1234"

The qr-code-data parameter is taken from QR code generated by PowerAuth RESTful services. Note that the QR code is signed; the signature is verified during offline authentication code computation. The method unlocks the knowledge-related authentication key using 1234 as a password.

The method does not execute any server calls due to its offline nature. The computed offline authentication code is used as an OTP, and it is available from the output of the command in decimal format, e.g.: 99961544-80193814.

Unlock the Secure Vault

Use this method to test secure vault unlock.

java -jar powerauth-java-cmd.jar \
    --url "http://localhost:8080/enrollment-server" \
    --status-file "/tmp/pa_status.json" \
    --config-file "/tmp/pamk.json" \
    --method "unlock" \
    --auth-code-type "possession_knowledge" \
    --password "1234" \
    --version "4.0" \
    --key-identifier "KEK_DEVICE_PRIVATE"
    --reason "NOT_SPECIFIED"

Uses the unlock method to unlock the secure vault for an activation with activation ID stored in the status file /tmp/pa_status.json, by calling the PowerAuth Standard RESTful API endpoint /pa/v4/vault/unlock hosted on root URL http://localhost:8080/enrollment-server. Uses the master public key and application identifiers stored in the /tmp/pamk.json file. Unlocks the knowledge-related authentication key using 1234 as a password. The reason why vault is being unlocked is NOT_SPECIFIED. The key identifier is KEK_DEVICE_PRIVATE.

Note: If a --password option is not provided, this method requires interactive console input of the password, in order to unlock the knowledge-related authentication key.

Sign Data Using Asymmetric Algorithm

Use this method to test obtaining the device private key and signing the data.

java -jar powerauth-java-cmd.jar \
    --url "http://localhost:8080/enrollment-server" \
    --status-file "/tmp/pa_status.json" \
    --config-file "/tmp/pamk.json" \
    --method "sign-asymmetric" \
    --auth-code-type "possession_knowledge" \
    --version "4.0" \
    --password "1234" \
    --data-file "/tmp/request.json"

Uses the sign-asymmetric method to unlock the secure vault for an activation with activation ID stored in the status file /tmp/pa_status.json, by calling the PowerAuth Standard RESTful API endpoint /pa/v4/vault/unlock hosted on root URL http://localhost:8080/enrollment-server. Uses the master public key and application identifiers stored in the /tmp/pamk.json file. Unlocks the knowledge-related authentication key using 1234 as a password. The reason why vault is being unlocked is SIGN_DATA. The key identifier used for unlocking the vault is KEK_DEVICE_PRIVATE.

The unlocked device private key is then used for signing data using an asymmetric data signature algorithm. The asymmetric signature algorithm depends on the cryptography version.

Note: If a --password option is not provided, this method requires interactive console input of the password, in order to unlock the knowledge-related authentication key.