Software Builder Factories

One options set. Two factories. Apps that can sync.

How to enable WildFly SSO 'single sign on'

A WildFly host can have numerous apps running on it and users will not want to sign-in to each app.

The WildFly Builder already stamps a sign-in page. Apps deployed to the same WildFly host use that sign-in screen and the same security domain. Single sign-on (SSO) is a separate server setting. It is only needed when two or more apps share the host and should share one session.

Add an application user

Use `add-user.sh` to add users and roles on the WildFly host.

Always choose **b) Application User**. Option **a) Management User** is only for the WildFly management console and `jboss-cli`. It does not sign anyone in to WildFly Builder apps. The management user named `admin` in the SSO commands below is a different account from these application users.

The groups WildFly Builder supports are `GUEST`, `USER`, and `ADMIN`. Enter one group, or a comma-separated list if the user needs more than one. Names are case-sensitive and must match the role names in the apps.

Example: add NewUser with role USER

/opt/wildfly/bin/add-user.sh
What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): b

Enter the details of the new user to add.
Using realm 'ApplicationRealm' as discovered from the existing property files.
Username : NewUser
Password recommendations are listed below. To modify these
restrictions edit the add-user.properties configuration file.
 - The password should be different from the username
 - The password should not be one of the following restricted values
   {root, admin, administrator}
 - The password should contain at least 8 characters,
   1 alphabetic character(s), 1 digit(s),
   1 non-alphanumeric symbol(s)
Password :
Re-enter Password :
What groups do you want this user to belong to?
(Please enter a comma separated list, or leave blank for none)[  ]: USER
About to add user 'NewUser' for realm 'ApplicationRealm'
Is this correct yes/no? y
Added user 'NewUser' to file
'/opt/wildfly/standalone/configuration/application-users.properties'
Added user 'NewUser' to file
'/opt/wildfly/domain/configuration/application-users.properties'
Added user 'NewUser' with groups USER to file
'/opt/wildfly/standalone/configuration/application-roles.properties'
Added user 'NewUser' with groups USER to file
'/opt/wildfly/domain/configuration/application-roles.properties'

WildFly writes both the standalone and domain property files. A standalone server uses the files under `standalone/configuration`.

What each prompt means

**What type of user do you wish to add?**
Answer `b`. Application users go into `application-users.properties` and are the accounts for the WildFly Builder sign-in page.

**Username**
The name typed on the sign-in page.

**Password**
The password typed on the sign-in page. It must differ from the username, must not be `root`, `admin`, or `administrator`, and must be at least 8 characters with 1 letter, 1 digit, and 1 symbol. Change `secret` in the SSO example below before using this on a shared host.

**What groups do you want this user to belong to?**
`GUEST`, `USER`, or `ADMIN`. After you confirm with `y`, that user can sign in on every WildFly Builder app that uses this realm.

Roles

All WildFly Builder apps use the same role names.

- **GUEST** can read app data and view app screens.
- **USER** can read app data, view app screens, and add or change app data.
- **ADMIN** can do everything a USER can do, and can open the Admin tab and run admin functions.

When to enable SSO

WildFly Builder stamps a Jakarta EE app with security hooks in the template. SSO is an Undertow setting on the host, plus the same application security domain on every war.

One app does not need SSO. Enable it when two or more apps share a host and should keep one session.

Without SSO, a sign-in on the host does not carry over. Each war has its own session. With SSO configured, the next catalog app on that host does not ask for a sign-in again.

Enable SSO on the WildFly host

These commands assume:

- A management user `admin` already exists (`add-user.sh`, option `a`). `jboss-cli` will prompt for that password unless you pass `--password`.
- Every war uses the application security domain named `other`. That is the Undertow default when `WEB-INF/jboss-web.xml` does not set a `security-domain`. If the template stamps another name, use that name instead of `other`.
- Users open the apps by a host name you control. The SSO cookie `Domain` must match that host.

`secret` below is the WildFly documentation example. Use a different store password and key password on a real server, and use the same value in `keytool` and in both CLI commands.

1. Create the keystore and the signing key

The Elytron key-store resource only points at a file. It does not create the file or the alias. SSO fails if `localhost` is missing from the store.

A trailing `\` continues the shell command on the next line. Paste the block as-is.

keytool -genkeypair -alias localhost \
  -keyalg RSA -keysize 2048 -validity 365 \
  -keystore /opt/wildfly/standalone/configuration/sso.keystore \
  -storetype PKCS12 \
  -dname "CN=localhost" \
  -keypass secret -storepass secret

2. Register the keystore in Elytron

/opt/wildfly/bin/jboss-cli.sh --connect --user=admin \
  --command="/subsystem=elytron/key-store=sso-keystore:add(\
path=sso.keystore, \
relative-to=jboss.server.config.dir, \
credential-reference={clear-text=secret}, \
type=PKCS12)"

`type=PKCS12` must match the file from `keytool`. Do not point this resource at a missing file. The `\` inside the quotes is only a line break. The shell joins those lines into one `--command` value.

3. Turn on Undertow single sign-on

Set `domain` to the host users type in the browser, without a port. A cookie with `Domain=sw-builder.local` is not sent to `localhost`, an IP address, or any other name.

For plain HTTP, keep `secure=false`. For HTTPS, set `secure=true`. `http-only=true` keeps the cookie out of browser scripts. The cookie path defaults to `/`, which is what cross-app SSO needs.

/opt/wildfly/bin/jboss-cli.sh --connect --user=admin \
  --command="/subsystem=undertow\
/application-security-domain=other\
/setting=single-sign-on:add(\
key-store=sso-keystore, \
key-alias=localhost, \
domain=sw-builder.local, \
credential-reference={clear-text=secret}, \
http-only=true, \
secure=false)"

Example for apps opened at `http://localhost:8080`:

/opt/wildfly/bin/jboss-cli.sh --connect --user=admin \
  --command="/subsystem=undertow\
/application-security-domain=other\
/setting=single-sign-on:add(\
key-store=sso-keystore, \
key-alias=localhost, \
domain=localhost, \
credential-reference={clear-text=secret}, \
http-only=true, \
secure=false)"

4. Reload

/opt/wildfly/bin/jboss-cli.sh --connect --user=admin --command="reload"

How it works

Each WildFly Builder app is its own war. `/booklet`, `/social`, `/security`, and the other catalog apps are different context roots on the same WildFly host.

Without SSO, Undertow keeps a session per war. A login on Booklet does not sign you in to Social or Security.

With SSO, Undertow issues a host-level SSO cookie after the first successful sign-in. The next war on that host, mapped to the same application security domain, sees that identity and skips the sign-in form.

The cookie and the `single-sign-on` setting live on the server. The wars only share that session when they use the same application security domain (`other`, unless the template sets another name). Signing out of one app does not always clear the session in the others. Treat logout as per-app unless you test it.