Skip to main content

PactFlow Environment Variables - 1.14 beta features

This page contains documentation for the usage of the JWT and OAuth2 features that are in beta release in PactFlow 1.14

Test JWT bearer authentication​

These settings can be configured in a YAML file, as per this example.
test_jwt_bearer_token_auth_enabled: true
test_jwt_bearer_token:
  iss: https://idp
  exp_leeway: 60
  jwks_url: https://idp/jwks
  aud: some-aud
  auth_config_handler: auth_ext_script.rb
  claim_mappings:
    idp_id: SomeUniqueIdentifier
    email: EmailAddress
    name: DisplayName
    first_name: FirstName
    last_name: LastName

PACTFLOW_TEST_JWT_BEARER_TOKEN_AUTH_ENABLED​

Whether or not to enable JWT bearer token authentication for testing purposes. This is not yet ready for production use.

Required: false
Default: false
Allowed values: true, false

PACTFLOW_TEST_JWT_BEARER_TOKEN__JWKS_URL​

The endpoint from which the JSON web key set can be retrieved to decode and verify the JWT used as the bearer token.

Required: false

PACTFLOW_TEST_JWT_BEARER_TOKEN__AUD​

The expected token audience ("aud") of the JWT.

Required: false

PACTFLOW_TEST_JWT_BEARER_TOKEN__ISS​

The expected token issuer ("iss") of the JWT.

Required: false

PACTFLOW_TEST_JWT_BEARER_TOKEN__EXP_LEEWAY​

The number of seconds of leeway to allow when verifying the expiration of the JWT, to allow for click drift between Pactlow and the Identity Provider.

Required: false
Default: 0

PACTFLOW_TEST_JWT_BEARER_TOKEN__AUTH_CONFIG_HANDLER​

The name of a Ruby script which will parse the decoded JWT and extract the roles and teams associated with the user. The script must be mounted into the PactFlow Docker container in the directory /home/pactflow/extensions.

Required: false

PACTFLOW_TEST_JWT__CLAIM_MAPPINGS__{KEY}​

This setting maps the IDP's claims in the JWT to the required PactFlow user attributes. This setting is best configured in the YAML file as a map. At least one of the keys must be called sub or idp_id. This will be used by PactFlow to uniquely identify the user from the Identify Provider. The other recommended keys are name, email, first_name and last_name.

eg.

test_jwt_bearer_token:
  # other configurations here ...
  claim_mappings:
    idp_id: "SomeUniqueIdentifier"
    name: "Name"
    email: "Email"
    first_name: "FirstName"
    last_name: "LastName"

When setting the claim mappings using environment variables, the key name must be uppercased and prefixed by PACTFLOW_TEST_JWT__CLAIM_MAPPINGS__ eg. PACTFLOW_TEST_JWT__CLAIM_MAPPINGS__EMAIL=Email. This will be mapped to a lower case { "email": "Email" } internally.

Required: false


Test OAuth2 authentication​

These settings can be configured in a YAML file, as per this example.
test_oauth2_auth_enabled: true
test_oauth2:
 client_id: "..."
 client_secret: "..."
 idp_url: "https://idp"
 authorize_url: "https://idp/authorize"
 token_url: "https://idp/token"
 jwks_url: "https://idp/jwks"
 token_issuer: "https://idp"
 token_audience: "..."
 token_exp_leeway: 60
 auth_config_handler: "auth_ext_script.rb"
 custom_authorize_params:
   resource: "SomeResource"
 claim_mappings:
   idp_id: "SomeUniqueIdentifier"
   email: "Email"
   name: "DisplayName"
   first_name: "FirstName"
   last_name: "LastName"

PACTFLOW_TEST_OAUTH2_AUTH_ENABLED​

Whether or not to enable OAuth2 authentication for testing purposes. This is not yet ready for production use.

Required: false
Default: false
Allowed values: true, false

PACTFLOW_TEST_OAUTH2__CLIENT_ID​

The unique identier by which the PactFlow application is known to the identity provider.

Required: false

PACTFLOW_TEST_OAUTH2__CLIENT_SECRET​

The client secret which the PactFlow application shares with the identity provider.

Required: false

PACTFLOW_TEST_OAUTH2__IDP_URL​

The identity provider's URL.

Required: false

PACTFLOW_TEST_OAUTH2__AUTHORIZE_URL​

The authorize endpoint of the OAuth2 provider.

Required: false

PACTFLOW_TEST_OAUTH2__TOKEN_URL​

The endpoint at which PactFlow can retrieve the JWT containing the user's information.

Required: false

PACTFLOW_TEST_OAUTH2__JWKS_URL​

The endpoint from which the JSON web key set can be retrieved to decode and verify the JWT returned by the token endpoint.

Required: false

PACTFLOW_TEST_OAUTH2__TOKEN_ISSUER​

The expected token issuer ("iss") of the JWT.

Required: false

PACTFLOW_TEST_OAUTH2__TOKEN_AUDIENCE​

The expected token audience ("aud") of the JWT.

Required: false

PACTFLOW_TEST_OAUTH2__TOKEN_EXP_LEEWAY​

The number of seconds of leeway to allow when verifying the expiration of the JWT, to allow for click drift between Pactlow and the Identity Provider.

Required: false
Default: 0

PACTFLOW_TEST_OAUTH2__AUTH_CONFIG_HANDLER​

The name of a Ruby script which will parse the decoded JWT and extract the roles and teams associated with the user. The script must be mounted into the PactFlow Docker container in the directory /home/pactflow/extensions.

Required: false

PACTFLOW_TEST_OAUTH2__CUSTOM_AUTHORIZE_PARAMS__{KEY}​

Allows custom authorize parameters to be set. These will be sent to the IDP in the request phase along with the default authorize parameters.

eg.

test_oauth2:
  custom_authorize_params:
    resource: "SomeResource"

When setting the custom authorize params using environment variables, the key name must be uppercased and prefixed by PACTFLOW_TEST_OAUTH2__CUSTOM_AUTHORIZE_PARAMS__ eg. PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__RESOURCE=SomeResource. This will be mapped to a lower case { "resource": "SomeResource" } internally.

Required: false

PACTFLOW_TEST_OAUTH2__CUSTOM_TOKEN_PARAMS__{KEY}​

Allows custom token parameters to be set. These will be sent to the token endpoint along with the default token parameters.

eg.

test_oauth2:
  custom_token_params:
    resource: "SomeResource"

When setting the custom token params using environment variables, the key name must be uppercased and prefixed by PACTFLOW_TEST_OAUTH2__CUSTOM_TOKEN_PARAMS__ eg. PACTFLOW_TEST_OAUTH2__CUSTOM_TOKEN_PARAMS__RESOURCE=SomeResource. This will be mapped to a lower case { "resource": "SomeResource" } internally.

Required: false

PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__{KEY}​

This setting maps the IDP's claims in the JWT to the required PactFlow user attributes. This setting is best configured in the YAML file as a map. At least one of the keys must be called sub or idp_id. This will be used by PactFlow to uniquely identify the user from the Identify Provider. The other recommended keys are name, email, first_name and last_name.

eg.

test_oauth2:
  # other configurations here ...
  claim_mappings:
    idp_id: "SomeUniqueIdentifier"
    name: "Name"
    email: "Email"
    first_name: "FirstName"
    last_name: "LastName"

When setting the claim mappings using environment variables, the key name must be uppercased and prefixed by PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__ eg. PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__EMAIL=Email. This will be mapped to a lower case { "email": "Email" } internally.

Required: false


API Tokens​

PACTFLOW_API_TOKENS__ENABLED​

Whether or not to enable the inbuilt PactFlow API tokens used for bearer authentication. Used to disable API tokens if an external Identify Provider is configured for API authentication.

Required: false
Allowed values: true, false