Single sign-on and SCIM provisioning

Single sign-on lets people sign in to the collector with your organization's identity provider instead of a local password. The identity provider handles multi-factor sign-in, so these accounts don't need the collector's own two-factor sign-in. With SCIM, the identity provider also adds, changes, turns off and removes their accounts by itself. Both are off until you turn them on.

Before you start

• Admin access to your identity provider: Microsoft Entra ID, Okta, Google Workspace, Keycloak, JumpCloud or another that speaks OpenID Connect or SAML 2.0. OpenID Connect suits most; use SAML when your provider only offers that.
• The address people use to open the collector, such as https://monitoring.example.com. Use HTTPS, ideally with a certificate from your CA (see the HTTPS certificate guide): sign-ins over plain HTTP can be read on the network.
• A plan for which groups become admins, operators and viewers, and which device types and sites each group may see.
• For OpenID Connect, outbound HTTPS from the collector to your identity provider. For SCIM it's the other way round: your identity provider sends changes to the collector, so it must be able to reach it.

1. Connect your identity provider

1. Open Settings › Single sign-on. Under Sign-in, choose the Protocol (OpenID Connect or SAML 2.0), enter the Collector address (how people open it), such as https://monitoring.example.com, and choose Save.
2. For OpenID Connect, copy the Redirect URI (https://monitoring.example.com/sso/oidc/callback) and register a web app with it at your identity provider. Enter the app's Issuer URL, Client ID and Client secret, and choose Save.
3. For SAML 2.0, give your identity provider the Entity ID (audience) and the Assertion consumer service (ACS) URL, or This collector's metadata. Then enter its Metadata address (https) and choose Fetch and import, or paste its XML under Or paste the metadata XML and choose Import. Review the settings and choose Save.
4. Choose Check the identity provider. For OpenID Connect it confirms the collector reached the issuer and says how many signing keys it found. For SAML it says how many signing certificates it has and gives the sign-in URL.

• Entra ID: the issuer is https://login.microsoftonline.com/<tenant ID>/v2.0. Add the groups claim to the token. It carries group object IDs unless you have it send names, so use whichever arrives in your rules.
• Okta: the issuer is https://<your org>.okta.com, or an authorization server's address. Add a groups claim with a filter.
• Google Workspace: the issuer is https://accounts.google.com. Google sends no groups, so use a * rule or a default role.
• Keycloak: the issuer is https://<host>/realms/<realm>. Add a Group Membership mapper with the claim name groups.
• SAML: set the name ID format to persistent or email address, send groups in an attribute named groups (Entra's own groups claim is found automatically) and turn assertion encryption off. Tick Fetch it again every day to pick up new signing certificates.
• Any provider: map the user name to something people can't change themselves, such as the UPN or work email address. If the provider's HTTPS certificate comes from your own CA, paste that CA under Advanced.

2. Map groups to roles, test, then turn it on

1. Under Roles and access, choose Add rule. Enter the Group exactly as your identity provider sends it and pick a Role: Viewer, Operator or Admin. Viewers and operators can be limited to some Device types and Sites.
2. Add a rule for your admins first, for example Network admins as Admin, then others, such as Warehouse as Operator limited to the Warehouse site. Rules are checked from the top and the first match wins; * matches everyone, and the arrows change the order.
3. Choose what happens When no rule matches: No access (sign-in refused), which is the default, Viewer (read only) or Operator. Then choose Save.
4. Choose Test sign-in and sign in at your identity provider in the new tab. The result shows whether you'd get in, your user name and groups, the rule that matched, and the role and access you'd get. Nothing is created or changed.
5. When the result looks right, tick Turn on single sign-on and choose Save. The sign-in page now has a button such as Sign in with Riverbend ID (the name comes from Button name) above the username and password form.

3. Optional: SCIM and single sign-on only

1. Under SCIM provisioning, tick Turn on SCIM and choose Save, then choose Create token. Copy the token now: it isn't shown again.
2. At your identity provider, set up provisioning with the SCIM base URL (tenant URL), such as https://monitoring.example.com/scim/v2, and the token. Assign groups to the app there so your rules can use them.
3. To turn off password sign-in, tick Single sign-on only, choose a Break-glass admin and choose Save. That local admin keeps password sign-in for when the identity provider is down; everyone else signs in with the identity provider.
4. If the break-glass password is lost while the identity provider is down, reset it on the collector itself with one of the commands below.

# On the appliance's console
monitaria users passwd <name>

# With Docker
docker exec -it -u monitaria monitaria python -m monitaria.collector.admin -c /data/config.json passwd <name>

Everyday use

• Accounts from single sign-on lists everyone who signed in or was added by SCIM, with their role, access, groups, last sign-in and status. The numbers under Status open the accounts that are turned off or without access.
• An account is created at someone's first sign-in. If you use SCIM and want only provisioned people to get in, untick Create an account at someone's first sign-in.
• Keep each account's role and access in step with its groups is on by default. Every sign-in, SCIM group change and rule change then applies the rules again, and someone no rule matches any more loses access and is signed out at once.
• These accounts have no password on the collector and aren't asked for its two-factor sign-in: your identity provider asks for the second step. Settings › Security lists them as signing in with single sign-on, never as without two-factor. Roles, access and removal are also under Settings › Users.
• With SCIM, turning someone off or deleting them at the identity provider signs them out of the collector at once and blocks sign-in.
• Audit trail lists settings changes, sign-ins and SCIM changes, and Download CSV exports them. Settings › Webhooks can also send single sign-on events to another system.

Security and limits

• The client secret is write-only and the SCIM token is stored only as a hash. Neither is shown again, logged or returned by the API.
• Every ID token and SAML response must carry a valid signature from your identity provider's published keys or certificates. The issuer and metadata addresses must use HTTPS.
• A local account with the same name is never taken over, and SCIM never touches local (password) accounts.
• One identity provider at a time. SAML has no encrypted assertions and no single logout, and SAML sign-ins started from the identity provider's app portal are refused. OpenID Connect has no front- or back-channel logout.
• Groups must arrive in the token or the user info. Entra ID's groups overage, for people in very many groups, isn't followed.
• User names must be 2 to 64 letters, digits and . _ @ -. If your provider's don't fit, map the user name to the email address.
• An account SCIM turned off can only be turned back on by SCIM.