Admidio Provisioning Plugin — keep accounts and groups of other systems in line with Admidio [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Admidio Provisioning Plugin — keep accounts and groups of other systems in line with Admidio ======

==== Description ====
A plugin for Admidio 6.0 and later that creates, updates, deactivates and deletes user accounts and groups on external systems according to Admidio's members and roles. Changes in Admidio reach the connected systems within seconds. It comes with three connectors:

  * **SCIM 2.0**, the standard protocol for user provisioning;
  * **Nextcloud**, through its OCS provisioning API: users, their profile data, enabled state and groups;
  * **Mailman 3**, through its REST API: roles become mailing lists, their members are subscribed by email address.

Other plugins can add further connectors.

==== Downloads ====
<WRAP download 60%>
{{admidioplugins>releases}}
</WRAP>

==== Installation ====
As administrator, go to Admidio's plugin manager (Admidio 6.0 or later and PHP 8.2 or later required, PHP extension ''curl'' needed), select "Add plugin" and upload the plugin ZIP file, then enable the plugin. The plugin creates its database tables when it is installed. Removing the plugin deletes them, including the record of which remote account belongs to which Admidio user -- disconnect or clean up the targets first.

=== Cron ===
Changes in Admidio reach the targets at the end of the request that made them. Membership start and end dates, which Admidio only knows as whole days, take effect with the daily reconciliation shortly after midnight. Run Admidio's maintenance jobs hourly, one line per organization; the plugin registers its job ''provisioning:sync'' there:

<code>
15 * * * *  php /path/to/admidio/admidio maintenance:run --organization=SHORTNAME --no-interaction --quiet
</code>

The command needs an acting organization administrator, for example through ''$gCliDefaults'' in ''adm_my_files/cli-config.php''. Without cron the first page request after midnight starts the reconciliation; ended memberships then stay active on the target until somebody opens Admidio.

==== Configuration ====
The menu entry **Provisioning** (below //Extensions//, visible to administrators) lists the targets. A target has

  * a **connection** (for SCIM: base URL, bearer token, OAuth 2.0 client credentials or HTTP Basic);
  * its **users**: every member of the organization, the members of selected roles, or -- if the target is linked to an SSO client -- everybody who may sign in to that client;
  * the **account name** (SCIM ''userName'') and the **attributes** taken from profile fields;
  * **groups**: configured on the target (members or leaders of roles), taken from the role mapping of the linked SSO client, and optionally one group for every other role;
  * a **verification** schedule that compares the target system with Admidio.

The status page of a target shows its queue, the last runs and every account or group that needs attention, and offers //Synchronize now//, //Verify now//, //Test connection// and //Retry//.

=== Connector notes ===
  * **Nextcloud:** the account name is the Nextcloud user ID and cannot change after the account was created. An existing user with that ID is taken over. New users get no password; Nextcloud mails them a link to set one, so they need an email address. Authenticate with an app password of an administrator. Since Nextcloud 35, changes to users, groups and memberships have to be confirmed with a password. An app password no longer suffices for this by default, but can be allowed from certain IP addresses: add the address of the Admidio server to ''allowed_no_password_confirmation_ranges'' in Nextcloud's ''config.php'' (behind a reverse proxy, the proxy also has to be in ''trusted_proxies''):
<code php>
'allowed_no_password_confirmation_ranges' => ['192.0.2.10/32'],
</code>
  * **Mailman 3:** the account name defaults to the email address, so users without one are not subscribed. A group name is the address of the list, or its local part together with the mail domain of the target. Lists are created and deleted only if the target allows it; otherwise a removed group only loses the subscriptions Admidio made. A changed email address moves the subscription.
  * **SCIM:** for services that deviate from the standard, a target can send complete resources (PUT instead of PATCH), work without groups, delete accounts instead of deactivating them, and send the OAuth client credentials in the request body or as HTTP Basic credentials.

==== What is touched, and what is not ====
  * Members of a group always get an account. Users without a value for the account name are not provisioned.
  * A user who no longer belongs to a target is removed from its groups and deactivated; only a user deleted in Admidio is deleted on the target.
  * Accounts and groups the plugin did not create or take over (matched by ''externalId'') are never touched.
  * Admidio only deletes what it created. An account or group that already existed on the target and was taken over is never deleted; only the memberships Admidio added are taken back. Members a group had before it was taken over are never removed.

=== Removing a target ===
  * **Disconnect** removes the target in Admidio. Its accounts and groups on the target system remain.
  * **Deprovision** deletes the groups and then the accounts Admidio created on the target system, and removes the target when that is done. The deletions go through the queue, so they survive interruptions; an item the target refuses keeps the target in the list until it is retried or the target is disconnected.

==== Settings ====
**Administration → Preferences → Login & security → Provisioning**

^ Setting ^ Default ^ Meaning ^
| Seconds per page request for synchronization | 5 | After a change, the targets are updated after the page has been delivered, for at most this many seconds. 0 leaves the synchronization to cron. |
| Allow targets in private networks | off | Allows target systems with private or reserved IP addresses and plain HTTP. Only switch this on if the target system is in your own network. |
| Notify administrators about problems | on | Sends the administrators of the organization at most one email per target and day if accounts or groups need attention. |

==== Command line ====
^ Command ^ Purpose ^
| ''provisioning:sync [--target=UUID] [--full] [--verify] [--budget=S] [--dry-run]'' | Run what is due (for cron) |
| ''provisioning:status'' | Targets, queues and last runs; exit code 3 if a target is paused or items need attention |
| ''provisioning:test --target=UUID'' | Test the connection |
| ''provisioning:queue --target=UUID [--retry] [--clear --yes]'' | Items that need attention; retry or clear |
| ''provisioning:deprovision --target=UUID --yes'' | Delete what Admidio created on the target system, then the target |

==== For developers ====
A connector extends ''AdmidioPlugin\Provisioning\Connector\Connector'' and is registered through the filter ''provisioning_connectors''. See the [[https://github.com/kainhofer/admidio-provisioning/|source code]] for a complete example and a small SCIM mock server for trying the plugin out.