Preselect an agency before sign-in

Use the PreselectAgency page when your application knows the user's agency and then opens an NG-SOS Portal page in the user's browser. It saves the agency selection for the next Identity Server login, so the user does not have to select the agency manually and the correct agency-specific sign-in providers can be loaded.

This page only prepares the browser for a later sign-in. It does not authenticate the user, issue an access token or grant access to an agency. When the browser is signed in for a different agency, the page ends that session first, so the next page the user opens asks for a new sign-in.

Build the URL

Open this URL in the user's browser:

https://identity.ng-sos.com/Account/PreselectAgency?agencyId={AGENCY_ID}&returnUrl={URL_ENCODED_RETURN_URL}

Parameter	Required	Description
agencyId	yes	UUID of an existing NG-SOS agency assigned during onboarding.
returnUrl	yes	Destination to open after saving the agency selection. URL-encode the complete value. Use an NG-SOS URL approved for your environment.

For example, this URL selects the agency and then opens the Portal incident overview:

https://identity.ng-sos.com/Account/PreselectAgency?agencyId=123e4567-e89b-12d3-a456-426614174000&returnUrl=https%3A%2F%2Fportal.ng-sos.com%2Fincident-list

Prefer constructing the URL with a standard URL library instead of concatenating query strings:

const agencyPreselectUrl = new URL(
  '/Account/PreselectAgency',
  'https://identity.ng-sos.com',
);

agencyPreselectUrl.searchParams.set(
  'agencyId',
  '123e4567-e89b-12d3-a456-426614174000',
);
agencyPreselectUrl.searchParams.set(
  'returnUrl',
  'https://portal.ng-sos.com/incident-list',
);

window.location.assign(agencyPreselectUrl.toString());

URL.searchParams applies the required query-parameter encoding. The page must be opened in a browser with JavaScript and browser storage enabled.

What the page does

1. The Identity Server checks that agencyId is a valid UUID belonging to a configured agency.
2. For a valid agency, the page saves the selection in the browser on the Identity Server origin.
3. If the browser is signed in for a different agency, that session is ended first.
4. The browser is redirected to returnUrl.
5. When the user is later sent to the Identity Server login page, the saved agency is selected and its configured sign-in providers are loaded.

The selected agency remains saved in that browser until another agency is selected.

Changing the agency

A user signed in for one agency must not keep working under the agency your application requests next, so the page compares the requested agency with the agency of the user signed in on the Identity Server:

• Same agency, or nobody signed in — the browser goes straight to returnUrl and the existing session is kept.
• Different agency — the user is signed out of the Identity Server and of every NG-SOS application that shares the session, in every open tab, and only then forwarded to returnUrl. Opening returnUrl therefore starts a new sign-in, with the requested agency already selected.

An agencyId that does not belong to a configured agency never ends a session.

Invalid parameters

• An invalid or unknown agencyId is ignored. The browser is still redirected, and any previously saved agency selection is left unchanged.
• A missing or rejected returnUrl redirects to the Identity Server root (/).
• Absolute return URLs are accepted only for configured NG-SOS application origins. The scheme, host and port must match. Identity Server local URLs are also accepted.
• Arbitrary external URLs and non-HTTP schemes such as javascript: are rejected.

See Portal URLs for supported Portal destinations. To sign a known user into the Portal without the normal interactive login, use the passwordless Portal sign-in flow instead.