Authenticating in Management API v1

Step 1: Generate keypair.

ruby -e "require 'openssl'; require 'base64'; OpenSSL::PKey::RSA.generate(2048).tap { |p| puts '', 'PRIVATE RSA KEY (URL-safe Base64 encoded, PEM):', '', Base64.urlsafe_encode64(p.to_pem), '', 'PUBLIC RSA KEY (URL-safe Base64 encoded, PEM):', '', Base64.urlsafe_encode64(p.public_key.to_pem) }"

Step 2: Include public key in the config/management_api_v1.yml at Barong.

You should give the ID to the key and put it in variable called keychain.

The variable keychain in config/management_api_v1.yml should look like:

    algorithm: RS256

The value is public key from URL-safe Base64 encoded PEM from the first step. The algorithm is signature algorithm you prefer.

Step 3: Configure JWT claims.

You can customize JWT verification options using variable jwt in config/management_api_v1.yml:

  verify_jti: true
  verify_aud: true
  exp_leeway: 180

The documentation is available at jwt repository.

Step 4: Configure security scopes.

The config/management_api_v1.yml already includes good docs for this step. You can find it at the bottom near variable scopes.

Step 5: Configure JWT provider and deliver private key.

The JWT provider can use Ruby Gem jwt-multisig for generating JWT with multiple signatures.

You should store private keys (ID, value, algorithm) somewhere in your application.

To generate JWS use the JWT::Multisig.generate_jwt(payload, private_keychain, algorithms).


require 'openssl'
require 'jwt-multisig'

payload = {
  exp:  1922830281, # Put here all the JWT claims.
  data: { foo: 'bar', baz: 'qux' } # Put here all the data your API action expects.

# You can choose what signatures the JWT should include.
private_keychain = {
  :'backend-1.mycompany.example' =>'BACKEND_1_PRIVATE_KEY_IN_PEM_FORMAT_BASE64_URLSAFE_ENCODED')),
  :'backend-2.mycompany.example' =>'BACKEND_2_PRIVATE_KEY_IN_PEM_FORMAT_BASE64_URLSAFE_ENCODED'))
algorithms = {
  :'backend-2.mycompany.example' => 'RS256',
  :'backend-.mycompany.example' => 'RS256'

jwt = JWT::Multisig.generate_jwt(payload, private_keychain, algorithms)

Kernel.puts JSON.dump(jwt) # The output will include serialized JWT.

The documentation for this method is available at The source code for jwt-multisig is available at GitHub. The example JWT is available at jwt-multisig source code.

Step 6: Make requests to API.

curl -v -H "Accept: application/json" -H "Content-Type: application/json" -d "JWT"

Where JWT is the result from previous step (serialized JWT).