What is Backend SSO; how does AGS pass the user's identity to the application?

Short answer

Backend SSO is AGS passing on the identity of the user it has verified by adding the identity to the request that goes to the Backend Service; the application does not ask the user to log in a second time. In TR7, this is done with the Backend SSO Configurations profile: the Injections in the profile add the identity to every request with a verified session as a Header, Basic Auth, Bearer Token or Cookie; the values are produced from the session with AGS Variables (e.g. AGS username, AGS user groups). The profile is selected in the Backend SSO Config field in the AGS settings of the vService; each vService uses a single profile, and while the field is empty, the identity is not passed on.

How Does It Work?

1. The user is verified in the access flow (Flowchart); the username, the e-mail, the groups and the attributes added with the Assign User Attributes step are written to the session.
2. The injections are added to every request that goes to the Backend Service from a user with a valid session. If a Condition is given to an injection, the injection is added only to the requests that match the condition; it is never added to requests without a session.
3. A header or cookie with the same name that the client itself sends is deleted first on every request; in the Basic Auth and Bearer Token injections, the header that is written (Authorization by default) is deleted as well. The identity information is written only by TR7.
4. AGS's own session cookies are removed from the request before it is forwarded to the Backend Service.

Type	Sent to the Backend Service	Typical use
Header	The header defined with Header name and Header value (e.g. X-Remote-User)	Applications that read the identity from a header
Basic Auth	Authorization: Basic …; produced from the Username source and Password source values	Applications that expect HTTP Basic authentication
Bearer Token	Authorization: Bearer …; the header name is changed with Header Name Override	APIs that expect a token
Cookie	The cookie defined with Cookie name and Cookie value	Applications that recognize the session with a cookie

Monitoring the Backend Service Session

The profile can also monitor the response of the Backend Service; both conditions are built from Conditions records with request and response side conditions:

• Backend Logout Condition: When the response that shows the Backend Service's own logout matches, the AGS session is closed as well and the user is redirected to the Redirect after Logout address; if the field is empty, / is used. The redirect method is selected with Redirect Modes: HTTP 302 redirect (default) and/or Custom header.
• Backend Session Lost Condition: When the response that shows that the Backend Service has dropped the session matches, the Backend Session Lost Strategy is applied. Log the user out (default) redirects the user to AGS's session loss page. Re-sync re-establishes the Backend Service session by running the step to which the Backend SSO (Re)Sync box in the Flowchart is connected; Max Auto Retries (default 2, 0–10) is the number of attempts made without requesting interaction from the user. In this strategy, the same step also runs on the first request of every newly opened AGS session.

If the two conditions match on the same response, the logout has priority.

Backend SSO in TR7

Where	Field	What it determines
AGS → Integrations → Backend SSO Configurations	Injections, Backend Session Lost Condition, Backend Logout Condition and the fields that depend on them	In which form the identity is passed on and how the Backend Service session is monitored
AGS-enabled vService → Flowchart → General Settings → Backend SSO	Backend SSO Config	The profile the vService uses
AGS-enabled vService → Flowchart	The Backend SSO (Re)Sync box	The step that runs in the Re-sync strategy; it is visible only while the strategy is Re-sync
AGS-enabled vService → AGS Management	The Corporate service sign-on box	A read-only summary of the selected profile

No code change is required on the Backend Service side; the application is configured to read the injected header or cookie as the user identity and is kept reachable only through TR7.

Common Misconceptions

• "Backend SSO is an IdP connection." The profile does not verify the user; it adds the identity already verified in the access flow to the request in the form the Backend Service expects. The IdP connection is set up with Authentication Providers.
• "If the client sends its own X-Remote-User header, the header reaches the application." Headers and cookies with the names in the profile are deleted on every request when they come from the client; the value is written only by TR7.
• "Redirect after Logout is also used on a session loss." This address is used only on a Backend Logout Condition match; the Log the user out strategy takes the user to AGS's session loss page.
• "The profile is enough for Re-sync." When Re-sync is selected, the Backend SSO (Re)Sync box in the Flowchart must be connected to a step.

How it is done in the documentation

• Backend SSO Configurations · What Are Backend SSO Configurations?
• Backend SSO Configurations · Operating Mechanism
• Variables · AGS variables
• Flowchart · Backend SSO Config

Related questions

• If I put AGS in front of my application, does the application need code changes?
• Is AGS an SSO solution; can it be used as an identity provider (IdP)?
• What is SSO (Single Sign-On)?
• What is a Bearer Token?