This guide takes an administrator through every login setting, user attribute, group, user account, local registration, impersonation, API key, SSO provider, and personal security and access screen.
The examples were created on a clean SQLite installation. Accounts, groups, and keys shown here exist only for documentation. Secrets and personal attribute values have been removed from screenshots. In production, use your own names, domains, lifetimes, and least-privilege rules.
Contents
- Login settings
- User attributes
- Groups
- Users and local accounts
- Local login and registration
- Impersonation
- API keys
- Common SSO workflow
- SAML
- SAML proxy
- CAS
- OIDC
- OAuth2
- Personal profile: security and access
- Verification and security checklist
1. Login settings
Open Settings → Users → Login settings . This page enables authentication methods for the application. Enabling a provider only makes its configuration and menu available; every individual profile must still be saved, activated, tested, and mapped correctly.
Main switches
- Local login enables username and password authentication stored by Simbioza.
- SimpleSAMLphp, CAS, OIDC, and OAuth2 enable the corresponding SSO profile groups.
- Break-glass local login keeps a separate direct administrator route available when normal local login is disabled. Protect that account with a strong unique password and use it only for recovery.
- Login duration is an inactivity limit in days (1–365), renewed while the signed-in user remains active. Use a shorter period on administrative and shared devices.
“Profile active” is not the same as the green check mark. Active means that the profile may be used. The green check and Tested and operational status appear only after a successful provider test and valid required mappings. An active profile may still be non-operational.
2. User attributes
Open User attributes . The model normally includes e-mail, first name, and last name. Add an attribute when the application must store a value outside the basic profile, such as an institution, department, employee number, or an external directory role.
Adding an attribute
- Enter a stable machine name in lowercase without spaces, such as
affiliation. - Provide separate Croatian and English labels.
- Choose the data type and configure Required , Registration , Profile , and Active independently.
- Save it. The new field becomes available in user profiles and in every SSO profile mapping table.
Mapping connects a Simbioza model field to the exact attribute name returned by the provider. Attribute names are exact: mail , givenName , and given_name are different fields. Test first, inspect the returned names, and only then enter the mappings. An SSO mapping does not automatically add the field to the public registration form.
Which fields are included in self-registration? The administrator chooses this per attribute. Registration controls whether a field appears in the public form, while Required rejects an empty value in contexts where that field participates. When both settings are enabled, the field is mandatory during self-registration. A required attribute must also have a valid SSO mapping for a provider profile test to become operational. In this example, affiliation stores the institution supplied by a provider and appears in the profile, so it is intentionally excluded from registration.
3. Groups
Groups collect users and carry permissions. The Administrator group is a protected system group and should not be used as a normal business group. Create separate least-privilege groups for departments, projects, or roles.
System and example groups in the English interface.\
- Choose Add group (the plus button), enter a recognisable Group name, and check Active.
- Choose Save groups. This screen does not contain a description or content permissions.
- Add or remove group membership from each user's details.
- Grant the group the required permissions in the settings of a workspace, page, calendar, or survey. SSO membership can also follow rules based on a mapped attribute.
Result: the group exists and can be selected when assigning permissions. Creating it alone does not open content to its members.
To disable a non-system group temporarily, clear Active and save. To delete it permanently, choose Delete group. On the separate confirmation screen, check the group name and the displayed effects on memberships and mapping rules, then choose Confirm deletion or cancel. User accounts remain. An empty name no longer deletes a group. Before confirming, check where the group is used for content access. A new group with the same name has a different identity and does not recover previous memberships or permissions. System groups cannot be deleted.
4. Users and local accounts
Open Settings → Users → Users to find accounts, inspect their state, and manage membership and access.
Creating a local user
- Select New user .
- Enter a unique login identifier, display name, and e-mail.
- Choose the local authentication source and assign a strong temporary password.
- Require a password change on first login.
- Assign only the required groups; administrator access must not be the default.
On the detail page, verify account activity, authentication source, linked external identities, and group memberships. Deactivation is usually safer than deletion because it preserves the audit trail. Never manually replace an external provider's stable subject identifier.
5. Local login and registration
Local login controls self-registration. Keep it disabled for closed systems and create accounts administratively or through trusted SSO. If enabled, registration creates an active ordinary account and signs the user in. It does not send a verification e-mail or prove ownership of the entered address. For a closed system, keep registration disabled and use administrator-created accounts or a trusted SSO provider. Publish an appropriate privacy notice before accepting registrations. The public form includes only user attributes whose Registration option is enabled; the SSO-only Institution field is therefore not shown here.
After testing, restore the intended production state. Passwords should be unique, sufficiently long, and stored in a password manager. Administrators must never ask users for their current password.
6. Impersonation
Impersonate user temporarily opens the application in the selected user's context. Use it for permission and display diagnostics, not for performing business actions on behalf of the user.
Impersonation does not test actual SSO authentication, MFA, or provider policy. Use the profile test or a dedicated test account for that purpose.
7. API keys
These screens are available when the API module is installed and enabled. An API key acts as its owner. Scopes can only reduce the owner's existing permissions; they cannot grant permissions the owner does not have. Use a separate key per integration, a descriptive label, the shortest practical lifetime, and the smallest set of scopes.
Direct key issuance
- Select the owner and only the required scopes.
- Set an expiry date and, if needed, an allowed IP address or network restriction.
- Create the key and immediately copy the secret to secure storage.
- The secret is shown only once. If it is lost, revoke the key and issue a new one.
User request and administrator approval
A user may request a key from the personal profile and explain its purpose. The administrator reviews owner, scopes, lifetime, and justification, then approves or rejects the request. After approval the user can reveal the secret once in the personal profile. When Notifications is enabled, an in-app notification also points to that screen. Neither the notification nor an e-mail should contain the secret.
8. Common SSO workflow
- Register the application with the provider and enter only the necessary endpoints, Client ID, and secret.
- Save the active profile. Existing secrets are never displayed while editing; leaving the secret field empty retains the server-side value.
- Select Test profile before guessing mappings. Complete a real login to collect the provider's actual attributes.
- Map subject, login, display name, and user fields from the returned names.
- Test again. Only Tested and operational together with a green check confirms a complete profile.
Allowed domains
The list restricts login to organizational domains. Enter one domain per line or a comma-separated list. example.org allows that domain and its subdomains; a suffix such as hr permits identifiers whose domain ends in .hr . An empty list imposes no domain restriction.
Domain source attribute must be the real provider attribute containing a value such as user@example.org or a domain. It is required only when the allowed-domain list is populated. Do not use a display name or another mutable value.
Public callback addresses
The provider must return the browser to the public URL of the same installation. Include a subdirectory when one is used: for an application at https://simbioza.example.org/simbioza , enter that complete value as the public base URL. It is not the internal PHP-FPM, container, or database address. Register the exact callback URLs shown by the profile.
9. SAML
A SAML profile depends on a separately installed and correctly configured SimpleSAMLphp . Its autoloader, SP auth source, certificates, metadata, and return URLs must already work. The path to vendor/autoload.php and the auth source name must match that installation.
10. SAML proxy and child profiles
A proxy instance represents one SimpleSAMLphp auth source that can expose several upstream providers. The Default tab defines the shared autoload path, auth source, and base mapping. Additional child tabs inherit the shared connection settings while keeping their own attribute mappings.
A proxy has no Allowed domains or Domain source attribute fields. This is deliberate: upstream providers may return different identifiers and domains. Enforce restrictions at the proxy or upstream provider, not through one shared Simbioza domain rule.
Default / AAI@EduHR
11. CAS
A CAS profile needs the server base URL and its login, validation, and logout endpoints. If a private CA chain is used, provide a readable certificate path. Never disable TLS validation to work around an incorrect certificate configuration.
12. OIDC
OIDC uses a Client ID and secret, authorization, token, userinfo, and optionally end-session endpoints. Scope must include openid , followed only by required data such as profile and email . Public redirect base URL is the complete public base address of this installation, including a subdirectory where present.
Use a forced-login parameter such as max_age=0 only when the provider supports it and Force login is enabled. Otherwise leave it blank to preserve a valid existing SSO session.
13. OAuth2
OAuth2 uses authorization, token, and userinfo endpoints plus the scopes required for user data. If the provider supports OpenID Connect, prefer OIDC because it standardizes identity and token validation. OAuth2 logout may require a dedicated endpoint, redirect parameter name, or hint; enter only values required by the provider documentation.
14. Personal profile: security and access
Open Personal profile from the user menu. The main section shows identity and custom attributes. Security and access displays group membership, local password state, linked external logins, and API key requests.
Link an external account only while you control both identities. Remove unknown or unused links, but first confirm another login method remains available. Change local passwords through this secure form, never through e-mail or an administrator message.
15. Verification and security checklist
- Keep at least one controlled administrator login available; store the break-glass account outside normal daily use.
- For every SSO profile, verify exact callback URLs, TLS certificates, minimum scopes, and secret rotation.
- Do not accept an active checkbox as proof. Require the green operational state after the repeated test.
- The subject must be an immutable provider identifier. Login and e-mail may change and are not always suitable primary identifiers.
- Test domain restrictions with both an allowed and a denied test account.
- Regularly review administrators, group memberships, linked external logins, active API keys, and pending requests.
- Never put passwords, client secrets, tokens, API secrets, or raw personal attributes in screenshots, documentation, tickets, or source control.
- After testing, remove or deactivate documentation accounts and keys that are no longer required.
After saving, test a normal login and a denied account. Confirm that each user sees only the content and actions assigned to their groups.
Comments
0There are no comments yet.
You must sign in to add a comment.