Smarter by Design.Simpler for Business
ags gateway
The ags gateway command manages the access flow in front of a vService: through which steps the user will pass, which profiles will be applied and how the access will conclude. Its panel equivalent is the AGS Management screen of the AGS-enabled vService.
The gateway record is created by itself
For every AGS-enabled vService a gateway record is created automatically and appears in the list with the vService name. For this reason the usual operation in this command is not add but update: first the record is found with list, then it is worked on. Taking a vService into the AGS scope is made from the panel; see AGS-Enabled vService List.
Command Summary
admin@TR7LBWAF01> ags gateway list # list the AGS-enabled vServices
admin@TR7LBWAF01> ags gateway show <id> # show the settings of one
admin@TR7LBWAF01> ags gateway update id <id> … # the usual operation
admin@TR7LBWAF01> ags gateway add gatewayMode <mode> … # rarely needed
admin@TR7LBWAF01> ags gateway delete <id> # delete the record
admin@TR7LBWAF01>
Writing Order
Step 1 Find the record
ags gateway listThe list shows only the AGS-enabled vServices; the records are named with the vService name.
Step 2 Write the flow steps
Every step is a list item and carries its own identifier. The steps are bound to each other with these identifiers.
--actions.0.id signin --actions.0.actionType agsForms --actions.0.actionProfileId <form>Step 3 Bind the transitions
Every action type has its own transitions; the transition value is the identifier of the step that will be gone to.
--actions.1.transitions.success allowed --actions.1.transitions.fail deniedStep 4 Determine the beginning
The first step of the flow is written separately.
--startAction signinRequired Fields
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | gatewayMode | Required | standaloneApp · portal · portalApp |
| 2 | portalUrl | Conditionally required | Only in the portal mode; the address of the portal |
In the updating the only required field is id; the mode and the other settings are written only if they will be changed.
The Gateway Modes
gatewayMode | What it does |
|---|---|
standaloneApp | It works in front of a single application; after the user is verified, they pass to that application |
portal | The portal that offers an application list to the user; the identity is verified here and it is passed to the applications from here |
portalApp | The application that takes over its identity from a portal; it does not run its own login flow |
The --startAction field is valid in the standaloneApp and portal modes. --privateTunnelDomain appears only in the portal mode and --trustedPortals.0 only in the portalApp mode; trustedPortals determines the portals whose session will be accepted.
The Flow Steps
The flow consists of the steps written with the --actions.N. prefix. In every step there are three things: the identifier, the type and the transitions according to the type.
| Field | Value |
|---|---|
--actions.N.id | The identifier of the step; the transitions point to this identifier |
--actions.N.actionType | The type of the step (the table below) |
--actions.N.actionProfileId | The profile that the step will use; only in the form, provider and MFA types |
actionType | What it does | The profile | Its transitions |
|---|---|---|---|
agsForms | It shows the login form | The form record | transitions.default |
agsAuthenticationProviders | It verifies the identity | The provider record | transitions.success · transitions.fail |
agsMFAs | It applies the second factor | The MFA record | transitions.success · transitions.fail |
decisionPoint | It branches according to a condition | — | transitions.yes · transitions.no |
switch | It branches according to a value | — | transitions.noMatch + the branch targets |
assignUserAttributes | It writes a user attribute into the session | — | transitions.default |
allow | It gives the access; the flow ends here | — | — |
deny | It refuses the access; the flow ends here | — | — |
The settings specific to the type
actionType | Its own settings |
|---|---|
decisionPoint | --actions.N.cond — the branching condition |
switch | --actions.N.switchVariable · --actions.N.switchMode (exact · prefix · suffix · contains · regex) · --actions.N.caseInsensitive · --actions.N.branches.M.pattern · --actions.N.branches.M.target |
assignUserAttributes | --actions.N.userAttributes.M.name · --actions.N.userAttributes.M.content |
allow | --actions.N.redirectUrl (if it is empty, the page that the user asked for) · --actions.N.redirectDelay (if it is empty, 3 seconds) · --actions.N.clientScript |
deny | --actions.N.customDenyMessage · --actions.N.denyTitle.… · --actions.N.denyText.… |
--actions.N.caseInsensitive is valid only in the matching formats other than regex.
The transition fields
The transition says with which step the flow will continue according to the result of the step. The value is the identifier written in the --actions.N.id field of the step that will be gone to.
| Field | What it does | In which step type |
|---|---|---|
--actions.N.transitions.default | It determines the step to be gone to after the step that has a single exit | agsForms · assignUserAttributes |
--actions.N.transitions.success | It determines the step to be gone to if the verification is successful | agsAuthenticationProviders · agsMFAs |
--actions.N.transitions.fail | It determines the step to be gone to if the verification is unsuccessful | agsAuthenticationProviders · agsMFAs |
--actions.N.transitions.yes | It determines the step to be gone to if the condition is met | decisionPoint |
--actions.N.transitions.no | It determines the step to be gone to if the condition is not met | decisionPoint |
--actions.N.transitions.noMatch | It determines the step to be gone to if no branch matches | switch |
The texts of the refusal page
In the deny step, when --actions.N.customDenyMessage true is written, the title and text fields open. Both of them use the same multilingual pattern as the form texts: the text is either written directly or is called from the dictionary.
| Field | What it does | What is written after it |
|---|---|---|
--actions.N.denyTitle.type | It selects where the title will come from | universal the text written directly (the default) · localized from the dictionary · default the text that the system produces · none no text |
--actions.N.denyTitle.text | It writes the title directly | The text that will appear; it opens only while type universal |
--actions.N.denyTitle.key | It calls the title from the dictionary | The key in the dictionary; it opens only while type localized |
--actions.N.denyText.type | It selects where the explanation text will come from | universal (the default) · localized · default · none |
--actions.N.denyText.text | It writes the explanation directly | The text that will appear; it opens only while type universal |
--actions.N.denyText.key | It calls the explanation from the dictionary | The key in the dictionary; it opens only while type localized |
The dictionary records are managed with ags profiles dictionaries.
The Bound Profiles
The gateway is bound with their identifiers to the records created separately:
| Field | Default | What it binds |
|---|---|---|
--pageTemplate | default | The template of the access pages |
--dictionary | default | The multilingual dictionary |
--sessionProtectionPolicy | — | The session protection policy |
--defaultLockoutPolicies.0 | Empty | The lockout policies |
--botProtectionPolicies.0 | Empty | The bot protection policies |
--notificationProfile | — | The notification profile |
--auditLogForwarders.0 | Empty | The audit record forwarders |
--backendSsoConfig | — | The backend SSO profile |
--backendSessionResyncAction | — | Only while an SSO profile is bound; the identifier of the step that re-establishes the backend session |
The Portal Applications
In the portal and portalApp modes the applications that will be listed in the portal are written with the --portalApps.N. prefix.
| Field | Value |
|---|---|
--portalApps.N.appName · --portalApps.N.appIcon | The name and the icon of the application |
--portalApps.N.accessMode | domainTunnel · tr7App · privateDomainTunnel |
--portalApps.N.appUrl | The address of the application; in the domainTunnel and tr7App formats |
--portalApps.N.appPoolId | The vService of the application |
--portalApps.N.privateTunnelScope | user (the address is fixed to the user) or session (it changes at every login); the default is user |
--portalApps.N.pathPrefix | Under which path prefix the application will be offered in the portal; it is written while more than one application under the same address is being separated |
For the privateDomainTunnel format the --privateTunnelDomain field is written on the portal gateway as well: the tunnel addresses are produced under this domain name.
The Other Settings
| Field | Default | Its function |
|---|---|---|
--agsRootPath | /ags-portal | The path on which the access pages are offered |
--agsCondition | Without a condition | When a condition is written, AGS comes into service only in the requests that match; if it is not written, all the requests of the vService pass through AGS |
--cookieDomain | — | The domain name of the session cookie |
--cookiePrefix | Empty | The prefix of the cookie name; when it is left empty, AGS_ is used. It is written in order to separate two gateways that share the same domain name |
--logLevel | info | error · warn · info · debug · silly |
--startAction | — | The first step of the flow; the value is the --actions.N.id identifier of that step. If it is not written, the flow does not start |
--privateTunnelDomain | — | Only in the portal mode. The base domain name of the privateDomainTunnel applications: every application is offered from the https://{hash}.{thisDomainName}/ address. A wildcard DNS record (*.domainname) and a certificate that covers it are needed for this domain name; in order for the portal session cookie to be able to reach these addresses, it must be under the scope of --cookieDomain |
--trustedPortals.N | Empty | Only in the portalApp mode and at least one of them is required: the portal gateways whose session will be trusted; every one of them with its own index |
Examples
# the form → the verification → allowed / denied
admin@TR7LBWAF01> ags gateway update id <vService> \
--actions.0.id signin --actions.0.actionType agsForms --actions.0.actionProfileId <form> \
--actions.0.transitions.default verify \
--actions.1.id verify --actions.1.actionType agsAuthenticationProviders --actions.1.actionProfileId <provider> \
--actions.1.transitions.success allowed --actions.1.transitions.fail denied \
--actions.2.id allowed --actions.2.actionType allow \
--actions.3.id denied --actions.3.actionType deny \
--startAction signin
admin@TR7LBWAF01>
# if the verification is successful, first MFA, then allowed
admin@TR7LBWAF01> ags gateway update id <vService> \
--actions.4.id mfa --actions.4.actionType agsMFAs --actions.4.actionProfileId <mfa> \
--actions.4.transitions.success allowed --actions.4.transitions.fail denied \
--actions.1.transitions.success mfa
admin@TR7LBWAF01>
admin@TR7LBWAF01> ags gateway update id <vService> \
--defaultLockoutPolicies.0 <lockout> --sessionProtectionPolicy <session> \
--botProtectionPolicies.0 <bot> --notificationProfile <notification>
admin@TR7LBWAF01>
admin@TR7LBWAF01> ags gateway update id <vService> --agsRootPath /signin --logLevel debug
admin@TR7LBWAF01> ags gateway show <vService> # verify the result
admin@TR7LBWAF01>
Updating and Deleting
The updating changes only the fields written; the flow steps are updated with the index and --actions.delete empties the whole of the flow. The delete command removes the record, but this is not a usual operation: the gateway lives together with the vService and is kept when AGS is turned off as well.
admin@TR7LBWAF01> ags gateway update id <vService> --actions.2.redirectUrl /panel --actions.2.redirectDelay 0
admin@TR7LBWAF01> ags gateway update id <vService> --actions.delete # empty the flow
admin@TR7LBWAF01>
Things to Know
- The flow is bound with the identifiers. The transition values are the step identifiers; a transition that points to an identifier that does not exist breaks the flow. While a step is being added, it is the safest to determine the identifier first and to write the transitions afterwards.
- Every flow must have an end. The
allowanddenysteps do not have a transition; the flow ends with them. - There are three types that require a profile. The form, provider and MFA steps are bound to a separate record with
actionProfileId; these records must be created first. - The index order is not the flow order. The running order of the steps is determined by
--startActionand the transitions; the--actions.Nindexes are only the place in the list. - The values with spaces and parentheses require quotation marks. The conditions, the content of the attributes and the refusal texts fall under this rule.
