Philstack's iMIS SSO Plugin for WordPress — Documentation

Plugin version: 3.13.0
Requires: WordPress 5.2+, PHP 7.2+, the php-curl extension
Author: Philstack LLC — support: [email protected]

Authenticate users into WordPress with the iMIS EMS Enterprise built-in OAuth SSO. The plugin signs members into WordPress using their iMIS credentials, synchronizes their profile data and roles from iMIS on every login, and provides role-based security for pages, posts, and media library documents.

How It Works

The plugin uses iMIS as the identity provider. iMIS must be the login page.

1. A visitor requests secured content (or clicks a login button) and is redirected to the iMIS SSO login page.
2. After entering credentials in iMIS, the visitor is redirected back to the WordPress SSO Return URL — a built-in plugin endpoint — with a refresh token.
3. The plugin exchanges the refresh token for an access token, then fetches the user's details from the $/Philstack/UsernameData IQA query (and, optionally, committee data from $/Philstack/UsernameDataCommittees).
4. The plugin matches the iMIS user to a WordPress user (by email, username, or full name, per your settings) or creates a new WordPress account.
5. The user's profile (first name, last name, email) is updated, custom mapped fields are synced to user meta, and WordPress roles are synchronized with the current iMIS data.
6. The user is logged into WordPress and returned to the page they originally requested. If the original page cannot be determined, the Fallback Return URL is used.

Requirements & Setup Overview

• WordPress 5.2 or newer, PHP 7.2 or newer.
• The php-curl PHP extension must be installed, enabled, and up to date (verify with the [ps-sso-curlcheck] shortcode).
• A valid Philstack license key.
• iMIS EMS Enterprise with a configured client application (Client ID + Shared Secret) and the two Philstack IQA queries installed (see iMIS IQA Requirements).
• No setup pages are required. As of 3.13.0 both SSO endpoints are built into the plugin:
  • SSO Return URL — https://example.org/?ps_sso_endpoint=return (pretty alias: https://example.org/ps-sso-return/). Copy it from the iMIS URL and Client Application Settings panel and configure it in iMIS as the SSO redirection target.
  • Login redirector — https://example.org/?ps_sso_endpoint=login (pretty alias: https://example.org/ps-sso-login/). Used automatically; original-page tracking works with nothing configured. Leave Login Redirector URL blank.

  Sites set up on earlier versions with [ps-sso-return] and [ps-sso-login-redirector] pages keep working unchanged. To retire them: point iMIS at the SSO Return URL above, clear the Login Redirector URL setting, then delete the two pages.

Step-by-step setup instructions with screenshots are available on the Philstack website.

Admin Menu Reference

The plugin adds a top-level Philstack's iMIS SSO menu to the WordPress admin (requires the manage_options capability, i.e. administrators).

Philstack's iMIS SSO (Settings)

Admin → Philstack's iMIS SSO

The main plugin page. It shows:

• Installed version and a support contact button.
• Directions — a link to the step-by-step setup guide and a summary of the SSO flow.
• Show Shortcode Descriptions — an expandable reference table of every shortcode (the same information as the Shortcode Reference below).
• License status — "Valid license confirmed!" with the time of last verification, or a validation-failure message.
• Force License Re-check button — clears the local license cache and re-validates against the Philstack licensing server immediately.
• Settings — every plugin option, organized into the sections documented in the Settings Reference.

Secured Content

Admin → Philstack's iMIS SSO → Secured Content

A list table of every post, page, custom post type item, and media document that has role-based security assigned (anything with security roles saved on it).

• Columns: Title (links to the edit screen), Content Type, Secured Roles (human-readable role names), Not-Logged-In Redirect (documents only — the mapped product page or URL), and Date.
• Filters: view links across the top let you filter by content type (All, Page, Post, Media, and any public custom post types).
• Search: a search box filters the listed content.

Use this screen to audit exactly which content on the site is restricted and to whom.

Role Manager

Admin → Philstack's iMIS SSO → Role Manager

Create, rename, and delete WordPress roles without a separate role-editor plugin.

• Add New Role — enter a Display Name and a Role Slug (lowercase letters, numbers, hyphens, and underscores; auto-suggested from the name; cannot be changed after creation).
• All Roles table — lists every role with its display name, slug, type (Built-in, iMIS Committee, or Custom), and a linked count of users holding it. Sortable and paginated (25 per page).
• Rename — every role (including built-in ones) can have its display name edited. Slugs never change.
• Delete — custom roles can be deleted individually or via the Delete Selected bulk action. Built-in WordPress roles (Administrator, Editor, Author, Contributor, Subscriber) cannot be deleted.
• Safe deletion with reassignment — before anything is deleted you see a confirmation screen showing how many users hold each role, and you choose a replacement role. Users whose only role is being deleted are moved to the replacement role; users holding other roles simply have the deleted role stripped.

Roles created here (or automatically by the SSO role sync) can be used in the page and document security role pickers.

Documentation

Admin → Philstack's iMIS SSO → Documentation

Opens this documentation (the flat-file HTML version bundled with the plugin) in a new browser tab, so the full reference is always available for the exact plugin version installed.

Settings Reference

All settings live on the main Philstack's iMIS SSO page and are stored together in one WordPress option (ps_imis_sso_plugin_options).

Licensing

iMIS URL and Client Application Settings

Redirection Settings

These control redirection behavior before, during, and after the SSO.

Authorization Required Message

Controls what happens when someone hits secured content, as an alternative to redirecting.

Both behaviors are global defaults — every secured page/post can override them individually in its security meta box. Combine with the [ps-sso-content-gate] shortcode to show a public teaser above the message.

Secured Documents

Access behavior for a secured document:

• Not logged in → redirected to the document's mapped product page (a free-form URL overrides a selected page); if none is mapped, the normal login flow runs (same as secured pages).
• Logged in with a required role → the file is streamed transparently (with HTTP Range support and private/no-cache headers).
• Logged in without a required role → redirected to the global Access Denied URL.

Role Assignment Settings

Username Matching Settings

Selects how the plugin matches incoming iMIS users to existing WordPress accounts (and how usernames are generated for new accounts):

If no match is found, a new WordPress user is created using the selected method. If the iMIS email already belongs to a different WordPress account, the new account is created with a modified, unique email to avoid the conflict (logged in debug mode).

Custom iMIS Field Sync

Sync additional iMIS IQA columns (e.g. academic or personalization data) into WordPress user meta on every SSO login — no code and no extra API calls required.

Details:

• Workflow: add the column to your $/Philstack/UsernameData IQA in iMIS, then list it in the mappings. Values are stored as user meta prefixed with ps_sso_ and can be displayed with the [ps-sso-user-field] shortcode.
• Reserved columns consumed by the core login flow cannot be mapped: username, imis-id, first-name, last-name, email, sso-role, sso-role-desc, company, sso-renewal-admin.
• Meta keys are sanitized to lowercase letters, numbers, and underscores.
• Synced meta is a mirror of iMIS: if a mapping is removed, a column disappears from the IQA, or the feature is disabled, the stale values are deleted on the user's next login.
• Synced values for each user are shown read-only on their WordPress profile screen (see User Profile Panels), so you can verify a mapping without enabling debug mode.
• If a mapped column is missing from the IQA response, a debug-mode log entry flags it (column-name typos are the most common issue).

WordPress UI Settings

Debug Settings

Content Security Tools

Role-Based Page Security (meta box)

Every public post type's edit screen (posts, pages, custom post types) gets a Philstack Role-Based Page Security meta box in the sidebar:

• Role checkboxes — check one or more roles to restrict the content to users holding any of those roles. Leave all unchecked to keep the content public.
• Not Logged In — Behavior — per-page override for anonymous visitors: Use global setting, Show message on this page, or Redirect to login. An optional custom message (rich text) overrides the global Authorization Required Message for this page only.
• Logged In, No Access — Behavior — per-page override for authenticated users lacking a required role: Use global setting, Show message on this page, or Redirect to access denied URL. An optional custom message overrides the global Access Denied Message for this page only.

The block editor shows a persistent notice banner stating whether the current page is public or restricted (and to which roles), updating live as you change the checkboxes.

Both custom-message boxes are full rich-text (WYSIWYG) editors with Visual and Text tabs. Under the block editor, WordPress relocates meta boxes in the page after they render, which can leave a rich-text editor visible but impossible to click into or type in; as of 3.12.2 the plugin detects that state and re-initializes the editor automatically, so no action is needed.

Teaser previews: place [ps-sso-content-gate] in the content to show everything above it publicly while gating everything below it (see the Shortcode Reference).

Message display replaces only the protected post's own content. Site furniture rendered by the theme — the sitewide footer, headers, sidebars, widgets, and secondary loops such as related-post lists — is left untouched and continues to display normally on a gated page.

Secured pages appear in the Secured Content admin list.

Document Security (media library panel)

With Secured Documents enabled, every media item (in both the media modal and the Edit Media screen) gets a Philstack Document Security panel:

• Restrict to roles — the same role picker as pages. Leave all unchecked to keep the file public. Securing a file relocates it into a protected store; unsecuring restores it. Existing embeds keep working.
• Not-logged-in redirect (product page) — where anonymous visitors are sent when they request the file. Choose a post type and use the searchable autocomplete to select any public content (e.g. a product page where the document can be purchased), or enter a free-form URL (the URL overrides the page selection). If left empty, anonymous visitors go through the normal login flow.

If a secured file cannot be moved into the protected store (e.g. the uploads directory is not writable), an admin notice appears and the file may still be publicly accessible until permissions are fixed and the media is re-saved.

Navigation Menu Login/Logout Items

Appearance → Menus gains a PS-SSO Authentication box that adds smart Login and Logout items to any menu:

• Editable labels (defaulting to the Login/Logout button labels from settings) become the initial menu item titles.
• The Login item is automatically hidden for logged-in visitors and links through the login redirector (with redirect_to set to the current page) — the configured Login Redirector URL if one is set, otherwise the built-in endpoint.
• The Logout item is automatically hidden for anonymous visitors and triggers the same AJAX logout flow as [ps-sso-auth-button] (including Single Logout when enabled).

User Profile Panels

On the WordPress user profile screen (Users → Profile / Edit User), the plugin displays:

• iMIS Committee Data — the user's synced committee assignments (name, code, position, term start/end), when committee storage is enabled.
• iMIS Custom Fields — a read-only table of every custom field synced for the user by Custom iMIS Field Sync, with the timestamp of the last SSO login sync.

Shortcode Reference

[ps-sso-return] — deprecated

No longer required. The SSO token exchange runs on the built-in SSO Return URL endpoint; point iMIS there instead of at a page. The shortcode is kept so existing installs keep working, and a page containing it can be deleted once iMIS is repointed.

When it does run, the plugin exchanges the token, fetches the user's iMIS data, logs them into WordPress, and forwards them to their original page (or the Fallback Return URL). Renders nothing on a normal visit; requires a valid license.

Execution point. Logging a user in sets an authentication cookie, and both that cookie and the final redirect are HTTP headers — so they can only be sent before the page produces output. The built-in endpoint runs on parse_request, before WordPress has even resolved a post. The legacy page flow runs on template_redirect, before the theme emits anything, with the shortcode itself as a last-resort fallback.

For the legacy page flow this matters because the page is detected by looking for the shortcode in the post content, not by waiting for it to render. A theme or page builder that never calls the_content() would otherwise skip the login entirely. Either way, a successful SSO return always responds with a 302 redirect and never a 200 HTML page.

Troubleshooting: if a POST to the SSO return page responds 200 OK with a rendered page instead of a 302, the login did not complete. On plugin versions before 3.12.1 this was the expected symptom when PHP output buffering was disabled — the <head> had already been sent, so wp_set_auth_cookie() and wp_redirect() both failed silently. Enable Debug Mode and check the log for Headers already sent: YES.

Trailing slashes. Configure the iMIS SSO return URL to match the WordPress permalink exactly, including a trailing slash if your permalink structure uses one (https://example.org/sso-return/). WordPress skips canonical redirects on POST requests, so a mismatch usually works — but any redirect placed in front of a POST discards the request body and the refresh token along with it.

[ps-sso-login-redirector] — deprecated

No longer required. Original-page tracking runs on the plugin's built-in login endpoint and is on by default; leave Login Redirector URL blank to use it. The shortcode is kept so existing installs keep working, and the page containing it can be deleted once the setting is cleared.

The behavior is identical either way: when a visitor arrives with a redirect_to query parameter, the redirector stores the originally requested URL (redundantly, via cookie, PHP session, and database transients, to survive restrictive hosting/CDN configurations) and forwards the visitor to the iMIS login page. After SSO completes, the visitor is returned to the stored URL. Already-logged-in visitors are sent straight back.

For security, redirect_to values pointing off-site are rejected and ignored — visitors are only ever returned to a URL on this site.

Page caching. The redirector is a pure side-effect page: it must execute PHP on every visit to work at all. If a full-page cache stores its response, PHP stops running and the login link silently does nothing. The plugin defends against this automatically:

• The redirect runs on parse_request (built-in endpoint) or template_redirect (legacy page), before the theme produces any output, so the 302 and its cache headers are always sent cleanly.
• Every available "do not cache" signal is emitted — DONOTCACHEPAGE, Cache-Control: no-store, Pragma: no-cache, and X-Accel-Expires: 0 (read by the Nginx page caches used by managed WordPress hosts such as Kinsta and WP Engine).
• Login links generated by [ps-sso-auth-button], the nav-menu login item, and role-based page security carry a per-request ps_nc value so a repeated URL cannot be served from cache.
• The built-in endpoint is not a post at all, so there is nothing for a page cache to key on beyond the query string. For the legacy page, the redirector is detected both by shortcode presence and by matching the request path against the Login Redirector URL setting, so the redirect still works with page builders that keep content out of post_content — or if the shortcode is accidentally removed from the page.

Editor safety. Both deprecated shortcodes have side effects — they set cookies, redirect, and exit. They now run only on live front-end page views: they are inert during admin, REST, AJAX, cron, feed, preview, and Elementor editor/preview requests, showing administrators a short placeholder instead. Rendering one during a REST save is what previously made publishing a page containing either shortcode fail with "Updating failed. The response is not a valid JSON response." — is_admin() returns false during a REST request, so the old guard never caught it.

If the login redirector stops working on a cached production site, enable Debug Mode and check the SSO log for Login redirector initialized. If that entry is absent after a failed login attempt, the request never reached PHP and the response is being served from a cache layer that is ignoring the headers above; exclude the redirector and SSO return URLs from the host's page cache.

[ps-sso-auth-button]

Displays a Login button for anonymous visitors or a Logout button for logged-in users. Labels and destinations come from the Redirection Settings. The login button routes through the login redirector (carrying the current page as redirect_to) — the configured Login Redirector URL if one is set, otherwise the built-in endpoint. The logout button triggers the AJAX logout flow described in Logout & Single Logout. Buttons use the theme's standard wp-block-button__link wp-element-button classes.

[ps-sso-profile-button]

Displays a button linking to the Profile page URL — only when the user is logged in. Renders nothing for anonymous visitors.

[ps-sso-renewal-button]

For logged-in users: if the user's iMIS data flags them as renewal-eligible (sso-renewal-admin = true from the UsernameData IQA), displays a button to the Renewal page URL; otherwise displays the Renewal not available message. Renders nothing for anonymous visitors.

[ps-sso-renewal-banner]

Like the renewal button, but renders a banner (div.ps-renewal-banner) containing a link with the Renewal banner text. Shown only to logged-in, renewal-eligible users; renders nothing otherwise.

[ps-sso-name-display]

Displays Welcome, First Last for logged-in users (using the WordPress first/last name synced from iMIS). Renders nothing for anonymous visitors.

[ps-sso-user-field]

Displays a custom iMIS field synced to the logged-in user's meta by Custom iMIS Field Sync.

[ps-sso-user-field field="grad_year" label="Graduation year: " default="—"]

For security, only fields produced by Custom Field Sync (the configured map or the ps_sso_custom_user_fields filter) plus the two built-ins can be displayed — the shortcode cannot read arbitrary user meta.

[ps-sso-welcome]

A testing and troubleshooting aid. Displays the auth button plus the logged-in user's WordPress account details (username, roles, name, email, registration date). When Debug Mode is on, it also shows the cURL status, key configuration values, and the full log of the last SSO run. Requires a valid license.

[ps_sso_nested_links]

Displays a bulleted list of the current page's child pages, filtered by role-based access: only children the current visitor is allowed to see (unsecured, or secured with one of the visitor's roles) are listed.

[ps-sso-content-gate]

A gating marker for teaser previews. Place it inside any post or page that has role-based security assigned: everything before the marker is shown publicly as a teaser; everything after it is hidden and replaced with the authorization-required / access-denied message for visitors who lack access. If the shortcode is not present on a secured page, the entire content is gated. (Applies when the "show message" behavior is active, globally or per-page.)

The gate only affects the protected post's content. The theme's template output — sitewide footer, header, sidebars, and widgets — renders normally around the teaser and message.

[ps-sso-curlcheck]

Diagnostic: prints whether the required cURL PHP extension is installed and available.

Logout & Single Logout

The logout button ([ps-sso-auth-button], the nav-menu Logout item, or any element with the #ps-imis-sso-logout-button ID) triggers an AJAX call that ends the WordPress session, then redirects. Two modes, controlled by the Single Logout setting:

• Legacy (default, unchecked): WordPress logs the user out, then the browser is redirected to the Logout URL. Sites wanting a crude single sign-out have historically pointed the Logout URL at the iMIS logout page; for iMIS 20.3.228+ that path is /Authentication/Logout (the old Logout.aspx no longer applies).
• Single Logout (checked, iMIS 20.3.228+): WordPress logs the user out, the browser then calls the iMIS Logout Endpoint (explicitly configured, or derived as {iMIS URL}/Authentication/Logout) to end the iMIS session, and finally lands on the Logout URL.

iMIS-initiated logout: when Single Logout is enabled, the plugin exposes a front-channel endpoint at {your-site}/?ps_sso_logout=1. Point the logout_target_url of your iMIS SingleLogout content record at this URL (the exact URL is displayed in the settings panel) so logging out of iMIS also ends the WordPress session. The endpoint logs the user out and redirects to the Logout URL, restricted to same-site destinations.

Role Synchronization

On every SSO login the plugin recalculates the user's WordPress roles from current iMIS data:

• The main SSO role comes from the IQA sso-role code (when Use the iMIS IQA "sso-role" field is checked) or the configured Default role. Missing roles are created automatically with Subscriber capabilities, using the sso-role-desc as the display name.
• Committee roles (when committee storage is enabled) are created and assigned per committee, prefixed iMIScommittee_ (e.g. iMIScommittee_finance-committee).
• SSO-managed roles that no longer appear in the iMIS data are removed, keeping WordPress in sync without manual cleanup.
• Built-in WordPress roles (Administrator, Editor, Author, Contributor) and the configured exempt role are never removed.
• Users holding the exempt role — and all administrators — are skipped entirely by role sync (profile and field data still update).
• Fuzzy matching prevents duplicate roles when iMIS casing or separators differ from an existing role (e.g. ILMA Member matches an existing ilmamember).

iMIS IQA Requirements

The plugin expects two IQA queries in iMIS (samples are shipped in the plugin's iMIS-iqa/ folder):

$/Philstack/UsernameData — returns the user's core properties:

Any additional columns you add to this IQA can be synced with Custom iMIS Field Sync — no code required.

$/Philstack/UsernameDataCommittees — returns committee assignments with properties CommitteeName, CommitteeProductCode, Position, TermStart, TermEnd. Only queried when Store iMIS Committee data as user meta is enabled.

Developer Hooks

Both hooks run on every SSO login, even when the settings-based Custom Field Sync is disabled.

Filter: ps_sso_custom_user_fields

Add, alter, or remove the custom fields stored as user meta during SSO login. Runs after the settings-based field map is applied, so you receive its output and can build computed/derived fields from any IQA column.

/**
 * @param array $custom_fields Unprefixed meta key => value. The ps_sso_ prefix
 *                             is added on write; keys are sanitized to [a-z0-9_].
 * @param array $imis_data     Every column returned by the UsernameData IQA
 *                             (Name => Value), mapped or not.
 * @param int   $user_id       The WordPress user ID being synced.
 * @return array
 */
add_filter('ps_sso_custom_user_fields', function ($custom_fields, $imis_data, $user_id) {
    // Derive a display badge from two raw IQA columns.
    if (!empty($imis_data['degree-program']) && !empty($imis_data['graduation-year'])) {
        $custom_fields['program_badge'] = $imis_data['degree-program'] . ' ’' . substr($imis_data['graduation-year'], -2);
    }
    return $custom_fields;
}, 10, 3);

Fields returned by the filter participate in the same lifecycle as mapped fields: they are written with the ps_sso_ prefix, tracked in the per-user index, displayable via [ps-sso-user-field], and cleaned up automatically when no longer returned.

Action: ps_sso_after_user_sync

Fires after an SSO login has fully synced the user (profile, roles, and meta) — on both the normal path and the exempt-role path. The API instance still holds a valid iMIS access token, so you can run additional IQA queries without re-authenticating.

/**
 * @param int      $user_id      The WordPress user ID.
 * @param array    $imis_data    Every column returned by the UsernameData IQA.
 * @param PsSsoApi $api_instance The authenticated API instance (access token
 *                               still valid for follow-up IQA queries).
 */
add_action('ps_sso_after_user_sync', function ($user_id, $imis_data, $api_instance) {
    // Example: record the member's company in a CRM sync queue.
    if (!empty($imis_data['company'])) {
        do_action('my_crm_queue_sync', $user_id, $imis_data['company']);
    }
}, 10, 3);

Typical uses: pushing data to other plugins or CRMs, running extra IQA queries, granting WooCommerce memberships, and custom audit logging.

Filter: ps_sso_auth_button_html

Customize the HTML markup rendered by the [ps-sso-auth-button] shortcode (the combined login/logout button). Runs every time the shortcode is rendered, whether the visitor is logged in or not.

/**
 * @param string $html               The generated button HTML (login markup when
 *                                    logged out, logout markup when logged in).
 * @param bool   $is_logged_in       Whether the current user is logged in.
 * @param string $login_url          The resolved login URL used when logged out
 *                                    (already includes any configured redirect_to).
 * @param string $login_button_text  Configured login button label.
 * @param string $logout_button_text Configured logout button label.
 * @return string
 */
add_filter('ps_sso_auth_button_html', function ($html, $is_logged_in, $login_url, $login_button_text, $logout_button_text) {
    if (!$is_logged_in) {
        return '<div class="ps-auth-button"><a href="' . esc_url($login_url) . '" class="my-theme-button">' . esc_html($login_button_text) . '</a></div>';
    }
    return $html;
}, 10, 5);

Note: the logout button's click behavior is bound by ID (#ps-imis-sso-logout-button) in assets/js/wp-imis-sso-logout-ajax.js. If you replace the logout markup, keep that id attribute on the clickable element or the AJAX logout won't fire.

Typical uses: swapping in theme-specific button classes/markup, adding icons, or wrapping the button in additional markup without editing plugin templates.

License Validation

The plugin validates its license with the Philstack licensing server using a fault-tolerant, cached system so temporary network issues (e.g. WAF blocks) never lock members out:

• Successful validations are cached and re-used for up to a 30-day grace period if the licensing server becomes unreachable. Genuinely invalid or expired licenses are enforced immediately — no grace period.
• A daily background check (WP-Cron) keeps the cache fresh without blocking any user-facing request. License checks only run where needed (admin pages and SSO shortcodes), never on every page load.
• The settings page shows the current status and when the license was last verified; the Force License Re-check button clears the cache and validates immediately.
• Admin notices appear when the cached validation is 7+ days old (warning) or the grace period has expired with the server unreachable (error). In debug mode an info notice shows the cache age.

Debugging & Troubleshooting

1. Enable Debug Mode in settings.
2. Visit a page containing [ps-sso-welcome] — it shows the cURL status, key configuration values, and the complete log of the last SSO run (user matching, role decisions, redirect resolution, API results). The log is session-based and clears when the browser is closed.
3. Check the PHP error log for the same events plus server-side detail (your hosting provider controls the log location; PHP logging may need to be enabled).
4. Use [ps-sso-curlcheck] to confirm the required cURL extension is available.
5. Verify custom field mappings on any user's profile screen (the iMIS Custom Fields panel) or via the Active mappings preview in settings.

Skip cURL cert validation exists for local development environments with self-signed certificates only — never enable it on a production site.