Install the Self Service Portal

On this page

Installing the Self Service Portal package and publishing a portal instance are two separate acts. The package installs a template of the portal under System\WebAppsTemplates\SSP, not a running site. The Web Configuration tool then creates an IIS web site or virtual directory from that template.

A published portal instance runs as two processes: an application hosted in IIS, and a Node.js process that this application starts. The IIS application forwards to the Node.js process every request that it does not answer itself.

For the portal's settings once it is published, see Self Service Portal Settings. For what customers do in the portal, see About the Self Service Portal.

Before you begin

  • The Web App, the Self Service Portal, and the API use the same IIS components:

    • Under Common HTTP Features: Static Content, Default Document, HTTP Errors, and HTTP Redirection.
    • Under Application Development: ASP.NET, .NET Extensibility, ISAPI Extensions, and ISAPI Filters.
    • Under Security: Request Filtering.
    • The IIS Management Console.
    • Static Content Compression.

    Static Content Compression and HTTP Redirection are alternatives: either one satisfies the requirement. If the instance will use Windows authentication, the Windows Authentication component under Security is also required. The Alloy Installer's IIS check for the Self Service Portal, however, always looks for the Windows Authentication component, whatever authentication method the instance will use, and fails without it. On IIS 7.5, 8.0, 8.5, and 10.0, the same check does not verify Static Content Compression or HTTP Redirection, so a passed check does not confirm that either one is installed.

  • The Self Service Portal needs the ASP.NET Core hosting bundle. When the Alloy Installer finds it missing for the Self Service Portal, the installer installs the hosting bundle it carries (version 8.0.11) and then restarts IIS, without asking and whether or not the hosting bundle's own setup succeeded. Every site on the server, Alloy or not, stops and restarts during that step. The Self Service Portal package run on its own does not install the hosting bundle.

  • You do not need to install Node.js. The Self Service Portal package carries its own Node.js runtime, and no prerequisite check asks for one. For a separately installed Node.js left on the server after an upgrade, see Upgrade a Production Installation.
  • You need a Database Access Key for the database the instance uses. The wizard's Database page lists the registered keys and can import one.
  • The instance URL must start with https://. The wizard's URL page accepts no other address.

In the installer

Install the portal package

Run the Self Service Portal package on its own, or install the Self Service Portal from the Alloy Installer's Advanced Installation page.

  • Windows asks for administrator elevation when the package starts.
  • The package installs one feature, which holds the portal files, a bundled Node.js runtime, the Alloy Launcher, and the PowerShell engine.
  • If an Alloy web application of version 8.7.2 or 2024.2 (24.2.0) is installed on the server, the package first closes every running copy of the Web Configuration tool, without a prompt, and deletes that version's Web Configuration tool. When the file is gone, the package writes the copy it carries in its place; when the file cannot be deleted, the package continues without a message and leaves it unchanged.

After the package is installed, its finish page offers the Run the Web Configuration check box, which runs the Web Configuration tool; the tool opens to create an instance from the installed template. The offer is not made in these cases:

  • The package is already installed.
  • The setup runs as an evaluation installation.
  • The installation is an administrative (network-image) installation.
  • A major upgrade was detected. In this case the package still runs the tool, which recreates the instances from their saved configuration instead of asking for the settings again.

When the Self Service Portal package is removed, it removes the instances that were published from its template.

On an upgrade, the package's Files Backup page states that the upgrade replaces all files and offers to back up the instance files. The backup check box is selected by default, and the backup folder defaults to a dated subfolder of Backups\ under the installation directory. Customized instance files survive only in that backup, with one exception: a hand edit to the instance's Web.config survives an upgrade when it sits between the XML comments BEGIN_CUSTOM_EF677073_10AC_44FE_AF1F_2AED27E06048 and END_CUSTOM_EF677073_10AC_44FE_AF1F_2AED27E06048 placed directly under the root element. After the upgrade, that span is restored at the end of the root element.

In the Web Configuration tool

To create an instance from the tool itself, choose File > Create > Self Service Portal.

Plan the instance

Configuring a portal instance settles four things:

  • Database: how the instance connects to the database, by importing a Database Access Key.
  • Web: whether the instance is a web site of its own or a virtual directory, and on which site.
  • The authentication method for the instance's visitors.
  • The link macro, Self Service Portal Link, that workflow notifications use to address this instance.

Create the portal instance

When you create an instance, the wizard runs its pages in this order. The Virtual Directory page is skipped when you install the instance as a web site.

  1. On Database, choose a registered Database Access Key in Key, or click Import Key.... Review SQL Server and Database, and click Next to test the connection.
  2. On Installation Type, choose Install as a Web site or Install into a virtual directory.
  3. On the Web Site page, select Choose an existing site: and pick the site, or select Create a new site with the following parameters: and fill in Site Name, IP Address, Host name, Port, and Physical Path. An instance installed as a web site defaults to the folder ...\WebApps\SSP\<site name>\root, with a number appended when that folder already exists.
  4. If you chose a virtual directory, enter its name and review Physical Path on Virtual Directory. When using an existing site, you can also select a directory already published under it.
  5. On the Authentication Method page, choose Windows Authentication or Standard Authentication. A new instance starts on Standard, with password authentication allowed. Single sign-on and LDAP are not chosen on this page. When the instance's settings are imported from an older installation, showing this page removes that installation's single sign-on providers, so an upgrade from a version earlier than 2024.2 whose configuration passes this page carries none of them over. If the older installation did not allow password authentication, the page then does not let you continue with Standard Authentication. For the single sign-on providers an instance offers, see Self Service Portal Settings. For how the methods work, see Authentication Methods.
  6. On URL, review the generated HTTPS address. If it differs from the Self Service Portal Link system macro, choose which value to keep:
    • Update system macro with instance URL saves the instance URL to the macro when you apply the settings.
    • Update instance URL with system macro copies the macro into the URL box.
  7. On Ready to Apply Settings, review the summary and click Apply. Use Previous to correct a choice before applying it.

For field validation, default folders, and the pages shown in each mode, see The publishing wizard.

For example, a portal published as hd on a site named Alloy Navigator defaults to ...\WebApps\SSP\Alloy Navigator\hd. If that folder already exists, the tool appends a number.

When you apply the settings, an empty Self Service Portal Link macro is filled with the instance URL. A macro that already holds a different value is rewritten only when you clicked Update system macro with instance URL on the URL page. You can copy the summary on the last page with Ctrl+C or from its shortcut menu.

Reconfigure an instance

Right-click the instance in the tool's tree and choose Configure, then Full, Database, or Web.

  • Full and Database start on the Database page. Web starts on the Installation Type page and skips the Database page.
  • A Database run restarts the web application when it applies the settings.
  • A reconfigure does not show the URL page. A Full or Web run fills an empty Self Service Portal Link macro but does not change a macro that already holds a value, and a Database run does not change the macro. The macro is also edited in the Settings App, in its Links group; see Macros Reference.
  • A hand edit to the instance's Web.config that sits between the two marker comments survives a reconfigure; the span is moved to the end of the root element.

In the Self Service Portal

Sign-in with Windows authentication

For the Self Service Portal, Windows authentication is a portal setting kept in the database. When it is on:

  • The portal does not show its password form.
  • Once the browser holds the portal's time-zone cookie, a customer whose browser has no signed-in session is sent to Windows sign-in, together with the address of the page they asked for, before any sign-in page appears. The customer types nothing into the portal. Whether the browser passes the Windows credentials silently or asks for them depends on IIS and the browser.
  • A session that started with a password or single sign-on is signed out and sent to Windows sign-in.
  • A refused Windows sign-in returns to the portal with an error, and the portal does not send the browser to Windows sign-in again.

The portal's Windows sign-in answers only when Windows authentication is enabled in IIS for the portal; otherwise it answers with HTTP status 404. After Windows authentication is turned off for the portal, a session that started with Windows sign-in is signed out.