ags backend-sso-configs

The ags backend-sso-configs command manages the profiles that determine how the identity of the user verified in AGS will be passed to the service at the backend and how the session state of that service will be tracked. Its panel equivalent is the Backend SSO Configurations screen.

The profile does two jobs at once: it adds identity information to the verified requests (a header, Basic Auth, a Bearer token or a cookie) and defines what will happen when the backend loses the session or completes its own logout.

Command Summary

TR7 WEB-CLI · ags backend-sso-configs

admin@TR7LBWAF01> ags backend-sso-configs list # list all of them

admin@TR7LBWAF01> ags backend-sso-configs show <id> # show one

admin@TR7LBWAF01> ags backend-sso-configs add name <name> … # new profile

admin@TR7LBWAF01> ags backend-sso-configs update id <id> … # change

admin@TR7LBWAF01> ags backend-sso-configs delete <id> # delete

admin@TR7LBWAF01>  

Writing Order

Step 1 Create the profile with its name

ags backend-sso-configs add name portal-sso

The only required field is the name; the profile can be created empty and its content can be filled in afterwards with an update.

Step 2 Add the injections

Every injection is a list item and is written with its own index. First the type, then the fields of that type are given.

--injections.0.type header --injections.0.headerName X-User --injections.0.headerValue <user-expression>

Step 3 Define the session behavior

What will happen when the backend loses the session or completes its own logout is determined with optional fields; if none of them is given, the profile only makes injections.

Step 4 Bind the profile to the vService

The profile does not work on its own; it is bound to the relevant gateway.

ags gateway update id <vService> --backendSsoConfig <profile>

Required Fields

Order	Field	Status	Value
1	name	Required	The name of the profile
—	backendLogoutRedirectHeaderName	Conditionally required	It is asked for only when customHeader is added to the redirection modes

Every field outside these is optional and is written with the -- prefix. The injections, which are the actual content of the profile, are optional fields too: a profile without injections is valid but does not pass an identity to the backend.

The Injections

Every injection is written with the --injections.N. prefix, with its own index. First the type is selected, then the fields of that type are given.

type	What it does	The fields of that type
header	Adds an HTTP header to the request	--injections.N.headerName · --injections.N.headerValue
basicAuth	Adds Basic Auth credentials	--injections.N.username · --injections.N.password
bearer	Adds a Bearer token	--injections.N.token (+ the optional --injections.N.bearerHeaderName)
cookie	Sends a cookie to the backend	--injections.N.cookieName · --injections.N.cookieValue

• The value fields accept a smart variable; the information of the verified user is passed from here. The variables that can be used change according to the flow and are listed with Tab. When a variable that contains parentheses is written, the value is put in double quotes.

Field	What it does	What is written after it
--injections.N.type	Selects the type of the injection; the fields of that type open accordingly	header · basicAuth · bearer · cookie
--injections.N.cond	Allows the injection to be applied only to certain requests	A condition expression. When it is left empty it is applied to every verified request

• If --injections.N.bearerHeaderName is not given, the header becomes Authorization.
• With --injections.N.cond the injection is applied only to certain requests; if no condition is given it is applied to every verified request.

The Session Loss and Logout Behavior

Field	Default	Its function
--backendSessionLostCond	Undefined	The condition that shows the backend has lost the session
--backendSessionLostStrategy	logout	What will be done on the session loss: logout logs the user out, resync runs the resynchronization step in the flow
--backendSessionLostMaxAutoRetries	2	Only while resync is selected; the number of silent attempts, 0 asks for user interaction every time
--backendLogoutCond	Undefined	The condition that shows the backend has completed its own logout; on a match the AGS session ends as well
--backendLogoutRedirectTo	/	The address to be redirected to after the logout
--backendLogoutRedirectModes.0	httpRedirect	The redirection mode: httpRedirect and/or customHeader
backendLogoutRedirectHeaderName	—	Required when customHeader is selected; the name of the header the address will return in

The condition fields

The --backendSessionLostCond, --backendLogoutCond and --injections.N.cond fields expect a condition expression. The expression can be written on the command line too; the terms that can be used at the point reached are completed with Tab. Building the conditions visually is more practical in the panel.

Examples

TR7 WEB-CLI · A) passing the identity with a header

admin@TR7LBWAF01> ags backend-sso-configs add name portal-sso \

--injections.0.type header --injections.0.headerName X-Auth-User \

--injections.0.headerValue <user-expression>

admin@TR7LBWAF01>  

TR7 WEB-CLI · B) two injections: a header and Basic Auth

admin@TR7LBWAF01> ags backend-sso-configs add name legacy-application-sso \

--injections.0.type header --injections.0.headerName X-Remote-User --injections.0.headerValue <user-expression> \

--injections.1.type basicAuth --injections.1.username <user-expression> --injections.1.password <password>

admin@TR7LBWAF01>  

TR7 WEB-CLI · C) redirection with a custom header after the logout

admin@TR7LBWAF01> ags backend-sso-configs update id <id> \

--backendLogoutRedirectModes.0 httpRedirect --backendLogoutRedirectModes.1 customHeader \

--backendLogoutRedirectHeaderName X-Auth-Redirect --backendLogoutRedirectTo /giris

admin@TR7LBWAF01>  

TR7 WEB-CLI · D) binding the profile to the vService

admin@TR7LBWAF01> ags backend-sso-configs list # find the id of the profile

admin@TR7LBWAF01> ags gateway update id <vService> --backendSsoConfig <profile>

admin@TR7LBWAF01>  

Updating and Deleting

The update asks for the identity with the id field and changes only the fields that are written. The injection list is updated with the index; --injections.delete empties the whole list.

TR7 WEB-CLI · update and delete

admin@TR7LBWAF01> ags backend-sso-configs update id <id> --injections.0.headerName X-User

admin@TR7LBWAF01> ags backend-sso-configs update id <id> --injections.delete # remove all the injections

admin@TR7LBWAF01> ags backend-sso-configs delete <id>

admin@TR7LBWAF01>  

Things to Know

• A profile does not work on its own. Until it is bound to a gateway it has no effect; the binding is done with ags gateway update and every vService uses a single profile.
• The values with parentheses require quotes. The command line counts the ( and ) signs as separators; when a smart variable that contains parentheses is written, the whole value is put in double quotes.
• The secrets are written on the command line. The Basic Auth password and the Bearer token are not asked for secretly; they appear on the line and fall into the command history.
• The resynchronization step is not defined here. The step to be run when the resync strategy is selected is determined in the flow editor of the vService.