apikeyman

README

Simple authentication service to store and validate API keys. Intended to be used with ORY oathkeeper or similar proxies to authenticate request using API keys.

Features

• Store API keys in sql database. Available databases are: postgres
• Generate API keys
• Check API keys with care
• Generate and validate signatures for requests using assymetric encryption. See below

Signature algorithms

Names are taken from this list

Algorithm	Description
RS256	RSASSA-PKCS1-v1_5 using SHA-256
RS512	RSASSA-PKCS1-v1_5 using SHA-512
ES256	ECDSA using P-256 and SHA-256
ES256K	ECDSA using secp256k1 and SHA-256
EdDSA	Ed25519

Public keys encoded as PKIX and private as PKCS8 asn1 binary. String encoding depends on usage - for REST API it is base64 encoded(same as middle part of PEM file), comman line uses PEM files.

Installation

Local

Download binary release from releases page. Start the service with the following command:

./apikeyman server --db postgres://user:password@localhost:5432/dbname

See Configuration for more details.

Docker compose

cd deploy/compose
docker-compose up

Helm chart

Repo: https://jaspeen.github.io/apikeyman

helm show all apikeyman --repo https://jaspeen.github.io/apikeyman

Usage

Command line

There are commands to generate, sign and verify signatures. See helm in apikeyman -h and example usages in cmd/apikeyman/tests/openssl-compat-tests.sh

Service

Create API Key

$ curl http://localhost:8080/apikeys -d '{"sub": "users:ci", "alg": "ES256", "name": "gh_action_token", "exp_sec": 86400, "extra": {"arbitrary": "data"}}' -H 'Content-Type: application/json'

{
  "apikey":"1:HFqAdqST5gdRrV8KT7YqCm2Hcby4C7Y7znD5CTAWiMLc",
  "publickey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt6RHimLFlLD8Q0ts+yNCdK39PxE4We9BAdFkhY6cX9RosnBYwD07GN88V1OySgUUOa3hYzehpFZrwJpmm4R6CA==",
  "privatekey":"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtp3DF6oKRBDKSFrtbkJNtlwxIhDNkJD7wYHMD0OVRqqhRANCAAS3pEeKYsWUsPxDS2z7I0J0rf0/EThZ70EB0WSFjpxf1GiycFjAPTsY3zxXU7JKBRQ5reFjN6GkVmvAmmabhHoI"
}

Check API Key

curl -X POST http://localhost:8080/check  -H 'X-API-KEY: 1:HFqAdqST5gdRrV8KT7YqCm2Hcby4C7Y7znD5CTAWiMLc' -d 'anybody'

{
  "sub": "users:ci"
}

Verify signature

curl -X POST http://localhost:8080/verify -H 'X-API-KEY: 1:HFqAdqST5gdRrV8KT7YqCm2Hcby4C7Y7znD5CTAWiMLc' -H "X-Timestamp: "$(date +%s) -H 'X-Signature: XXX' -d 'anybody'

{
  "sub": "users:ci"
}

Get key

curl http://localhost:8080/apikeys/1:HFqAdqST5gdRrV8KT7YqCm2Hcby4C7Y7znD5CTAWiMLc

{
  "sub": "users:ci",
  "alg": "ES256",
  "name": "gh_action_token",
  "exp_sec": 86400,
  "extra": {
    "arbitrary": "data"
    }
}

Search keys by subject

curl http://localhost:8080/apikeys?sub=users:ci

[
  {
    "sub": "users:ci",
    "alg": "ES256",
    "name": "gh_action_token",
    "exp_sec": 86400,
    "extra": {
      "arbitrary": "data"
    }
  }
]

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.