pay-publicauth

Payments Public API Authentication Service

API Specification

The API Specification provides more detail on the paths and operations including examples.

View the API specification for publicauth in Swagger Editor.

API Keys

Anatomy of an API key:

e.g. api_live_u3tl8gajo9paj0xki31jm1psr3v21m5urh50zoa7a262w4ntzoo6cqhu82

api_live_ u3tl8gajo9paj0xki31jm1psr3 v21m5urh50zoa7a262w4ntzoo6cqhu82
--------- --------------------------
 PREFIX      RANDOM BASE32 STRING
------------------------------------ --------------------------------
                   TOKEN                        CHECKSUM

Item	Definition
TOKEN	randomly generated base 32 string, 130 bits entropy, variable length, optionally includes a human readable prefix
CHECKSUM	hmacSha1(TOKEN + TOKEN_API_HMAC_SECRET), base32 encoded. Always 32 characters long
TOKEN_API_HMAC_SECRET	secret provided via application environment
TOKEN_DB_BCRYPT_SALT	bcrypt salt provided via application environment
TOKEN_HASH	bcrypt(TOKEN, TOKEN_DB_BCRYPT_SALT) - the value we actually store in the database
TOKEN_LINK	randomUUID() - stored in tokens table, used as an external id for the API key

API key generation algorithm:

1. TOKEN := generate a 130 bit random number and encode to base32, optionally prefix with a human-readable string based on the token account type
2. CHECKSUM := hmacSha1(concat(TOKEN, TOKEN_API_HMAC_SECRET))
3. API_KEY := concat(TOKEN, CHECKSUM)
4. TOKEN_HASH := bcrypt(TOKEN, TOKEN_DB_BCRYPT_SALT)
5. Store TOKEN_HASH in database
6. Return API_KEY

API key validation algorithm:

1. API_KEY is provided as Authorization: Bearer someverylongstringandachecksum
2. Extract API_KEY := someverylongstringandachecksum
3. Split the string at a known character index based on the length of the sha1 suffix, i.e. TOKEN := someverylongstring ACTUAL_CHECKSUM := andachecksum
4. Verify that hmacsha1(concat(TOKEN, TOKEN_API_HMAC_SECRET)) == ACTUAL_CHECKSUM
5. TOKEN_HASH := bcrypt(TOKEN, TOKEN_DB_BCRYPT_SALT)
6. Look up TOKEN_HASH in database; return true iff found

Environment variables

NAME	DESCRIPTION
ADMIN_PORT	The port number to listen for Dropwizard admin requests on. Defaults to 8081.
BIND_HOST	The IP address for the application to bind to. Defaults to 127.0.0.1.
DB_HOST	The hostname of the database server.
DB_PASSWORD	The password for the DB_USER user.
DB_SSL_OPTION	To turn TLS on this value must be set as ssl=true. Otherwise must be empty.
DB_USER	The username to log into the database as.
JAVA_HOME	The location of the JRE.
JAVA_OPTS	Commandline arguments to pass to the java runtime. Optional.
PORT	The port number to listen for requests on. Defaults to 8080.
RUN_APP	Set to true to run the application. Defaults to true.
RUN_MIGRATION	Set to true to run a database migration. Defaults to false.
TOKEN_API_HMAC_SECRET	HMAC secret to create the signature for the API Key.
TOKEN_DB_BCRYPT_SALT	Salt used for the hashing algorithm (bcrypt) to hash tokens before being stored in DB.

Integration tests

The command to run the integration tests is:

mvn verify

Licence

MIT License

Vulnerability Disclosure

GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. Please refer to our vulnerability disclosure policy and our security.txt file for details.