ags mfas

The ags mfas command manages the configurations that define the second factor asked for from the user after the password: a code from an authentication application, a code sent by e-mail or a code transmitted over an HTTP service. Its panel equivalent is the Multi-Factor Authentication screen.

The MFA configuration does not work on its own; it is added to the flow of the gateway as a step of the agsMFAs type and becomes the profile of that step.

Command Summary

TR7 WEB-CLI · ags mfas

admin@TR7LBWAF01> ags mfas list # list all of them

admin@TR7LBWAF01> ags mfas show <id> # show one

admin@TR7LBWAF01> ags mfas add name <name> method <method> … # new record

admin@TR7LBWAF01> ags mfas update id <id> … # change

admin@TR7LBWAF01> ags mfas delete <id> # delete

admin@TR7LBWAF01>  

Writing Order

Step 1 Write the name

ags mfas add name totp-verification

Step 2 Select the method

method totp

It takes three values: totp, emailOtp, httpOtp. After the method is selected, only the fields of that method are asked for.

Step 3 Write the fields of the method

Which fields will be asked for is given method by method below; every remaining setting comes with its default value.

Step 4 Add it to the flow

ags gateway update id <vService> --actions.N.actionType agsMFAs --actions.N.actionProfileId <mfa>

Required Fields

Order	Field	Status	Value
1	name	Required	The name of the configuration
2	method	Required	totp · emailOtp · httpOtp
3	totpIssuerName	Conditionally required	Only in the totp method
3	otpChannel · httpUrl · httpMethod	Conditionally required	Only in the httpOtp method

In the emailOtp method there is no required field other than the name and the method; every setting from the code length to the validity period comes with its default.

The Methods

method	Where the code comes from
totp	It is produced in the authentication application of the user
emailOtp	It is produced by TR7 and is sent to the e-mail address of the user
httpOtp	It is produced by TR7 and is transmitted to the channel selected with an HTTP request (an SMS gateway, an e-mail service or a custom service)

The Fields Method by Method and an Example Command

totp

Order	Field	Status	Value
1	name	Required	The name of the configuration
2	method	Required	totp
3	totpIssuerName	Required	The institution name that will appear in the authentication application

Optional setting	Default	Value
--totpAlgorithm	SHA1	SHA1 · SHA256 · SHA512; most of the applications support SHA1
--totpDigits	6	6 or 8
--totpPeriod	30	The renewal period of the code, in seconds
--totpWindow	1	The clock drift tolerance; every step is one period long
--totpAllowManualEntry	true	If the QR code cannot be read, it allows the secret key to be entered by hand
--totpAllowBackupCodes	true	It allows the user to produce backup codes

TR7 WEB-CLI · totp

admin@TR7LBWAF01> ags mfas add name totp-verification method totp totpIssuerName Institution

# a longer code and a wider tolerance

admin@TR7LBWAF01> ags mfas add name totp-tightened method totp --totpIssuerName Institution \

--totpDigits 8 --totpWindow 2 --totpAllowBackupCodes false

admin@TR7LBWAF01>  

emailOtp

Its required field consists of the name and the method. The code is sent to the e-mail address of the user.

Optional setting	Default	Value
--otpLength	6	The number of characters of the code
--otpType	numeric	numeric or alphanumeric
--otpAllowResend	true	It allows the user to ask for a new code
--otpEmailSource	—	The expression from which the e-mail address to which the code will be sent will be taken
--otpExpiration.val · --otpExpiration.unit	—	The validity period of the code
--otpResendCooldown.val · --otpResendCooldown.unit	—	The period to be waited in order to ask for a new code

TR7 WEB-CLI · emailOtp

admin@TR7LBWAF01> ags mfas add name email-code method emailOtp \

--otpLength 8 --otpType alphanumeric --otpExpiration.val 180 --otpExpiration.unit s

admin@TR7LBWAF01>  

httpOtp

The code is produced in TR7 and is transmitted to the user with an HTTP request. For this reason both the channel and the request are defined.

Order	Field	Status	Value
1	name	Required	The name of the configuration
2	method	Required	httpOtp
3	otpChannel	Required	sms · email · custom
4	httpUrl	Required	The address to which the request will go
5	httpMethod	Required	The request method (GET, POST… the default is POST)

Optional setting	Default	Value
--otpPhoneSource	—	In the sms channel; the expression from which the telephone number will be taken
--otpEmailSource	—	In the email channel; the expression from which the e-mail address will be taken
--httpBodyType	json	none · multipartForm · urlEncodedForm · json · raw
--httpTimeout	30	In seconds
--httpFollowRedirects	true	It follows the redirections
--httpSuccessConditions.0	statusCode	statusCode · cookie · redirectUrl · jsonata
--httpExpectedStatusCodes.0	200	The status codes considered a success
--httpHeaders.0.name · --httpHeaders.0.value	—	The request headers
--httpQueryParams.0.name · --httpQueryParams.0.value	—	The query parameters
--httpBodyParams.0.name · --httpBodyParams.0.value	—	The field name and value to be written into the body; it opens while the body format is json, multipartForm or urlEncodedForm and at least one pair is needed
--namespace	The default route table of the device	The route table from which the request will go out

The fields that open according to the success condition and the body format:

Field	What it does	What is written after it
--httpExpectedCookieName	It determines the name of the cookie that must be present in the answer for it to be considered a success	The cookie name. It is required when cookie is added to the success conditions
--httpExpectedRedirectUrl	It determines the address to which the answer will redirect for it to be considered a success	The address. It is required when redirectUrl is added to the success conditions
--httpSuccessJsonataExpression	It determines the expression that the answer body must meet for it to be considered a success	A JSONata expression. It is required when jsonata is added to the success conditions
--httpRawBody	It determines the raw content of the request body	The body text. It is asked for when the body format raw is selected

TR7 WEB-CLI · httpOtp (an SMS gateway)

admin@TR7LBWAF01> ags mfas add name sms-code method httpOtp \

otpChannel sms httpUrl https://sms.institution.local/send httpMethod POST

# when a header is added, the fields specific to the type are written with the -- prefix as well

admin@TR7LBWAF01> ags mfas add name sms-code-2 method httpOtp \

--otpChannel sms --httpUrl https://sms.institution.local/send --httpMethod POST \

--httpHeaders.0.name Authorization --httpHeaders.0.value <key>

admin@TR7LBWAF01>  

The Period Fields

The period fields consist of two parts: the value and the unit.

Field	Default
--otpExpiration.val · --otpExpiration.unit	The unit s
--otpResendCooldown.val · --otpResendCooldown.unit	The unit s
--trustDuration.val · --trustDuration.unit	30 days

The Settings Common to All the Methods

Setting	Default	Its function
--trustDevice	false	It shows the "trust this device" option on the login screen
--trustDuration.val · --trustDuration.unit	30 days	The period for which the device is trusted
--lockoutBehaviour	inherit	How the lockout policies will be applied at this MFA point: inherit · override · extend · disabled
--lockoutPolicies.0	lockout_username	The policies to be applied when override or extend is selected

Updating and Deleting

TR7 WEB-CLI · update and delete

admin@TR7LBWAF01> ags mfas update id <kimlik> --trustDevice true --trustDuration.val 7 --trustDuration.unit d

admin@TR7LBWAF01> ags mfas update id <id> --httpHeaders.delete # empty the headers

admin@TR7LBWAF01> ags mfas delete <kimlik>

admin@TR7LBWAF01>  

The method can be changed in the updating as well; when it is changed, the required fields of the new method must be given too.

Things to Know

• The configuration does not work on its own. It is not used without being added to the flow of the gateway as an agsMFAs step; the success and failure transitions of the step are also defined there.
• If there is one -- on the line, the fields specific to the method take -- as well. name and method are always without a prefix.
• The values with parentheses and spaces require quotation marks. The source expressions and the values with more than one word are written with double quotation marks.
• The lockout policies can be bound from here as well. When --lockoutBehaviour override or extend is selected, separate policies are applied for this MFA step.