Docs

String Interpolation Syntax

Suggest Edits

The purpose of string interpolating is to be able to extract dynamic data at run-time, from previous stages of an authentication flow into the following stages. This will be needed in cases when it is impossible to hardcode such dynamic data, for example, temporary IDs or tokens. The string interpolation block will be replaced by the actual dynamic data that is generated each time the particular authentication flow runs.

The syntax allows you to create a template (interpolation string) for the value to be extracted from the specified location. While using a template to configure a request, you can only reference requests and responses already executed during the current flow.

The interpolation string uses the double curly braces {{ and }} as the boundaries for each block and consists of two general parts: Source data and Functions, that should be defined in order to do the interpolation.

The source of data configuration consists of the following parts:

  1. Data context: each interpolation string must start with the auth_object prefix which defines the context of the interpolation execution. In the future, you will be able to pull information from other contexts such as secrets vaults, etc.
  2. Stage from which the data is to be collected
  3. Request/response: The request or response of that stage
  4. Location inside the request/response: URL, headers, body

📘

Note:

The authentication process produces HTTP requests and receives HTTP responses. A request-response pair is named stage in terms of the template syntax.

Functions :

  • Functions are separated by the | character, and support chaining multiple functions with the same character.

Format: {{ <source of data> | function 1 | function 2 }}

The parts comprise the following components:

PartComponents
Source of data1. Data context: auth_object

2. Stage: stage name, e.x. Stage1

3. Request/response: request, response

4. Location inside the request/response: url, headers, bodyThere are three common use cases:

5. The exact stage number is known.
Example: {{ auth_object.stages.stage1.response.headers | <function> }}

6. The exact stage number is unknown or can change (any_stage).
When using the any option the matcher will look across all the stages for a match with your interpolation, and return the latest one (chronologically) from the flow.Example: {{ auth_object.stages.any.response.headers | <function> }}3. Alternatively, if the source data needs to be generated outside of the authentication flow, such as OTP token generation, see the OTP chapter.
FunctionThe string interpolation syntax supports the chaining of functions executing from left to right, and each function should start with the pipe character | . The functions are applied in the relevant order. It means that in the example below, first the get will be applied, and then the match.

Functions have two components:

1. Name: get, match, encode
2. Parameters: see functions description below for additional info.Parameters are separated from the function name by a colon:Example: {{auth_object.stages.stage1.response.headers | get: '/Set-Cookie' }}Example with chained functions: {{ auth_object.stages.stage1.response.headers | get: '/Set-Cookie' | match:/accessToken":"(.\*)"}/}}

Supported pipes

get

Returns the value associated with the XPath, or undefined if there is none.

Parameters:

  • xpath - xpath string

Example: {{ auth_object.stages.stage1.response.headers | get: '/Set-Cookie' }}

match

Retrieves the result of matching a string against a regular expression.

Parameters:

  • regex - regular expression
  • group - number of the capture group (optional, default 1)

Example: {{ auth_object.stages.stage1.response.body | match:/accessToken":"(.*)"}/}}

encode

Encodes the value to some format.

Parameters:

  • format - base64, url or none (optional, default none)

Example: {{ auth_object.stages.stage1.response.body | encode: 'base64' }}

Generating data dynamically

Mock data

If you need to generate random data to use during the configuration of an authentication object, you can apply one of the following Faker.js data generators:

  • uuid
    Example: {{ <$faker>.datatype.uuid }}

  • number
    Example: {{ $faker.datatype.number }}

otpToken

Inserts an OTP (one-time password) with preconfigured parameters.

In order to use an OTP token you need to first configure it. To learn how to configure an OTP, see Creating Authentication page. Then you can use interpolation syntax to add it to your authorization flow.

Example: {{ auth_object.otps.token1 }}

Updated 4 months ago