Public URLs on a Self-Hosted Server

Everything Aeon hands an identity provider is built from two addresses: the staff API's public base URL and the staff web client's public base URL. On an Atlas-hosted site both are set on every deploy and you can skip this page. On an on-premises install they live in the API's web.config, the installer stamps them, and the API refuses to start without them. This page is for whoever administers that server.

The two settings

Setting	What it is	What it feeds
PublicUrls__ApiBaseUrl	The staff API's public base URL, as a browser or an identity provider reaches it. On a standard install that is your site's HTTPS address followed by /StaffAPI, for example https://aeon.example.edu/StaffAPI.	The default SP entity ID, the ACS and Single Logout URLs, the SP metadata, the OpenID Connect redirect URI, the login URL handed to browsers, and the subject of a generated SP certificate.
PublicUrls__FrontendBaseUrl	The staff web client's public base URL. On a standard install, your site's HTTPS address followed by /Staff, for example https://aeon.example.edu/Staff.	Where a browser is sent after a single sign-on sign-in, and the address in SSO invitation emails.

Emailed password-reset and account-setup links are the exception: they use the StaffWebURL customization key, and fall back to PublicUrls__FrontendBaseUrl only when that key is empty or invalid. See Keep StaffWebURL in step.

A value has to be an absolute http:// or https:// URL. A path is allowed (the virtual application), a trailing slash is ignored, and a query string, fragment, or user name in the URL is refused. Use https://: Aeon accepts http:// on a real host name with only a logged warning, but single sign-on then fails at its last step, as the overview's prerequisites explain.

Where they live

Both are environment variables in the API's web.config, in the <environmentVariables> block of the <aspNetCore> element. With the default install root that file is C:\Program Files\Atlas\Aeon\StaffAPI\web.config:

<aspNetCore processPath=".\AtlasSystems.Aeon.WebApi.exe" ...>
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
    ...
    <environmentVariable name="PublicUrls__ApiBaseUrl"
                         value="https://aeon.example.edu/StaffAPI" />
    <environmentVariable name="PublicUrls__FrontendBaseUrl"
                         value="https://aeon.example.edu/Staff" />
  </environmentVariables>
</aspNetCore>

They are read once, when the API starts. Nothing on the Single Sign-On page writes them: its Public URLs card shows the values and where each came from, read-only.

The API does not start without them

Outside local development, a missing, empty, or invalid value stops the API at startup. The error names the setting and its environment-variable spelling, for example "'PublicUrls:ApiBaseUrl' is not configured (app setting or environment variable PublicUrls__ApiBaseUrl)", and is written to the API's stdout log, the files under StaffAPI\logs whose names start with stdout. Fix the value in web.config and the API starts on the next request.

How the installer sets them

Install.ps1 stamps both values into web.config:

• -StaffWebUrl sets the staff web client's address. It is written to the StaffWebURL customization key as well as to PublicUrls__FrontendBaseUrl. When omitted, the installer keeps an existing StaffWebURL key; if there is none, it derives a candidate from the patron web WebURL key (the same host, https://, plus /Staff) and uses it only after checking that the address responds as the staff client.
• -StaffApiUrl sets the API's address. When omitted, the installer derives it from the staff web address: its origin plus /StaffAPI.

The derivation is right for a standard install and wrong wherever the public name differs from what the server can see: a custom DNS name, a reverse proxy, or a renamed virtual application. None of those are detectable from the server, so pass -StaffApiUrl whenever you know the public API address, and -StaffWebUrl alongside it.

When the installer could not resolve a value it says so at the end of the run, in a warning that includes "THE API WILL NOT START until it is set", and names the parameter to re-run with and the file to edit.

What happens on an update

Update.ps1 carries web.config across the upgrade, so edits you have made survive. It also backfills each setting that is absent or empty:

• PublicUrls__FrontendBaseUrl from the StaffWebURL customization key.
• PublicUrls__ApiBaseUrl from -StaffApiUrl if you pass it, otherwise from the frontend value's origin plus /StaffAPI.

A value that is already present is never rewritten by an update. The API address anchors the SP entity ID your identity provider has been configured to trust, so an upgrade must not move it; change it deliberately, as below. Where the updater can resolve neither source it prints a similar "THE API WILL NOT START" warning.

Changing a value

1. Edit the value attribute in web.config. Saving the file restarts the API process on the next request; recycling the API application pool in IIS Manager also works.
2. If you changed the API address and single sign-on is configured, the ACS URL and Single Logout URL have changed with it, and so has the SP entity ID unless an explicit spEntityId is set on the Advanced (JSON) tab. Re-register Aeon at your identity provider, or have them re-import the SP metadata, before staff sign in again.
3. If a signing certificate was generated while the API address was wrong, its subject names the wrong host. Generate a new one and rotate it in, as in Managing Service Provider Certificates.
4. If you changed the frontend address, set the StaffWebURL customization key to the same value, below.

Keep StaffWebURL in step

The StaffWebURL customization key (Customization Manager, Web Interface → General) owns the address in emailed staff links and the return address for Atlas support sign-ins, and it outranks PublicUrls__FrontendBaseUrl for those. Single sign-on reads only the web.config value. Keep the two equal. When they disagree, the API logs a warning at startup and again whenever it builds an emailed link, which is the shape a database restored from another environment takes: the key still names that environment's server.

Confirm the result

On the Single Sign-On page's Service provider tab (Public URLs under OpenID Connect):

• The Public URLs card shows both addresses marked from deployment configuration. An address marked built-in default means the API is running with ASPNETCORE_ENVIRONMENT set to Development or Testing, the only environments that start without the settings; a deployed server should be set to Production.
• Under SAML, an amber warning on the Service provider card means the API address is localhost or another loopback address. Generate certificate (Add certificate once one exists) stays disabled until it is fixed.
• Compare with patron web URL derives both addresses from the patron web WebURL key the way the installer does and says whether each matches the configured value. A difference is not always wrong, but it is worth explaining.
• The SP entity ID, Assertion Consumer Service (ACS) URL, and Single Logout URL name your public host, and so does the SP metadata when you fetch Download SP metadata's address from outside the server. The metadata is served only while single sign-on is enabled.