Square 9 Identity Manager (S9IM) Synchronization | GlobalForms 10 Administration

Bring users and groups from Square 9 Identity Manager (S9IM) into GlobalForms, so the same accounts and passwords work in both products.

This feature requires GlobalForms version 10.10 or greater.

What synchronization does

Groups become roles. Each S9IM group is matched to a GlobalForms role with the same name. If no role exists, GlobalForms creates one. You can then use these roles on a form's Access settings.
Users are created or updated. Each S9IM user is added to the GlobalForms User resource, or updated if they already exist, and given the roles for their S9IM groups plus the Authenticated role.
Existing roles are kept. Synchronization adds roles but does not remove roles you assigned in GlobalForms.
Passwords stay in S9IM. When a synchronized user signs in, GlobalForms checks the password with S9IM. Password changes in S9IM take effect immediately.
Administrator access is protected. By default, S9IM groups cannot give users the GlobalForms Administrator role.

Before you begin

The address of the S9IM management API, for example http://s9im-server:5000/api. The GlobalForms server must be able to reach it.
An S9IM API key.
Access to config\local.json on the GlobalForms server.

Turn on S9IM synchronization

Add an s9im section to config\local.json:

JSON

{
  "s9im": {
    "enabled": true,
    "apiUrl": "http://s9im-server:5000/api",
    "apiKey": "<S9IM API key>",
    "domain": "",
    "interval": 60,
    "allowAdminRole": false
  }
}

Restart the GlobalForms service.
Sign in to GlobalForms as an administrator and select Synchronize S9IM in the menu bar to run the first synchronization.
When it finishes, check that the expected roles and users appear.

Settings

Setting	Default	Description
`enabled`	`false`	Turns S9IM synchronization and S9IM sign-in on or off.
`apiUrl`	(none)	Required. Address of the S9IM management API
`apiKey`	(blank)	Required. S9IM API key. You can enter the key on its own, or as `bearer <token>` or `masterkey <value>`.
`domain`	(blank)	Optional prefix for synchronized user names. For example, `s9im` stores user `jdoe` as `s9im\jdoe`. See below.
`interval`	`0`	Minutes between automatic synchronizations. `0` turns off automatic synchronization; you can still synchronize manually.
`allowAdminRole`	`false`	When `true`, an S9IM group named for the GlobalForms Administrator role can make its members GlobalForms administrators. Leave this `false` unless you fully trust S9IM group membership to control administrator access.

Choosing a user name prefix

`domain` setting	Result
Blank (default)	S9IM users keep their user names. GlobalForms checks S9IM first for every sign-in. Use this when S9IM is your main source of accounts.
A prefix, such as `s9im`	S9IM users are stored as `s9im\username`. This keeps them separate from accounts created directly in GlobalForms that have the same name.

With a prefix, users can sign in with or without it. For example, jdoe and s9im\jdoe both work.

Running synchronization

Manually: sign in as an administrator and select Synchronize S9IM in the menu bar. A message shows while it runs and when it finishes.
Automatically: set interval to the number of minutes between runs, then restart the service.

Synchronize again after you add users or change group membership in S9IM. Password changes do not need a synchronization.

Troubleshooting

Message or symptom	Cause and fix
`S9IM synchronization is disabled by configuration`	Set `s9im.enabled` to `true` in `local.json` and restart the service.
`Configuration is missing s9im.apiUrl parameter`	Add `apiUrl` to the `s9im` section.
`S9IM request failed (401)…` or `(403)…`	The API key is wrong or does not have access. Check `apiKey`.
The synchronization fails to connect	Check `apiUrl` and that the GlobalForms server can reach the S9IM server and port.
A user can't sign in after synchronization	Check that the user exists and is active in S9IM, and try their user name both with and without the prefix.
A user did not become an administrator	This is expected while `allowAdminRole` is `false`. Assign the Administrator role in GlobalForms, or set `allowAdminRole` to `true`.