WordPress Plugin (auris-sso)

The auris-sso WordPress plugin adds Auris-powered single sign-on to any WordPress site. When a visitor clicks the Auris login button, they are redirected to the Auris hosted login page. On successful authentication, the plugin automatically creates or updates a WordPress user account (just-in-time provisioning) and maps Auris roles to WordPress roles.

The plugin is built on top of the auris/sdk PHP library and adds no other dependencies.

Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• auris/sdk (PHP SDK) — bundled in the plugin’s vendor/ directory
• An application registered in the Auris Console with the WordPress callback URL added as an Allowed Callback URL

Installation

From a ZIP File

1. Download the auris-sso.zip distribution file.
2. In the WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Upload the zip file and click Install Now.
4. Click Activate Plugin.

Using Composer (Advanced)

If your WordPress project uses Composer for dependency management:

{
  "repositories": [
    {
      "type": "path",
      "url": "packages/auris-sso"
    }
  ],
  "require": {
    "auris/auris-sso": "*"
  }
}

composer install

Then activate the plugin in Plugins → Installed Plugins.

Configuration

Just-in-Time User Provisioning

When a user authenticates through Auris for the first time, the plugin creates a new WordPress user account automatically. On subsequent logins, the existing account is updated with the latest profile data from Auris.

Fields synchronized from Auris to WordPress:

If the email address already exists in WordPress, the plugin links the Auris identity to the existing account rather than creating a duplicate.

Role Mapping

Configure how Auris roles map to WordPress roles in Settings → Auris SSO → Role Mapping.

The default mapping is:

To customize the mapping, add entries in the settings table. Roles are evaluated in order — the first matching Auris role determines the WordPress role. If the user has multiple Auris roles, the first match in the table wins.

Example custom mapping:

If no mapping matches, the user is assigned the default WordPress role configured in Settings → General → New User Default Role.

Login Button

Shortcode

Add the Auris login button to any page or post using the shortcode:

[auris_login_button]

Optional attributes:

[auris_login_button label="Sign in with your company account" class="my-custom-class"]

Template Function

Add the login button to your theme’s template files:

<?php
if (function_exists('auris_sso_login_button')) {
    auris_sso_login_button([
        'label'    => 'Sign in with Auris',
        'class'    => 'button button-primary',
        'redirect' => home_url('/dashboard'),
    ]);
}

Replacing the Default WordPress Login Form

To replace the standard wp-login.php form entirely, enable Replace WordPress Login Form in Settings → Auris SSO. When enabled, visiting /wp-login.php automatically redirects visitors to the Auris hosted login page.

Action Hooks

The plugin fires WordPress action hooks at key points in the authentication flow. Use these to run custom code after SSO events.

auris_sso_user_created

Fires when a new WordPress user is created via JIT provisioning.

add_action('auris_sso_user_created', function (int $wpUserId, array $aurisUser) {
    // $wpUserId — the new WordPress user ID
    // $aurisUser — the Auris user array: id, email, firstName, lastName, roles, metadata
 
    // Example: send a welcome email
    wp_mail(
        $aurisUser['email'],
        'Welcome to ' . get_bloginfo('name'),
        'Your account has been created.'
    );
 
    // Example: assign custom user meta
    update_user_meta($wpUserId, 'auris_tenant', $aurisUser['tenant'] ?? '');
 
}, 10, 2);

auris_sso_user_updated

Fires when an existing WordPress user’s profile is updated on login.

add_action('auris_sso_user_updated', function (int $wpUserId, array $aurisUser) {
    // $wpUserId — the existing WordPress user ID
    // $aurisUser — the updated Auris user data
 
    // Example: log the login event
    error_log(sprintf(
        '[Auris SSO] User %s (WP ID: %d) signed in.',
        $aurisUser['email'],
        $wpUserId
    ));
 
}, 10, 2);

auris_sso_login_failed

Fires when the Auris callback is received but authentication fails (invalid state, token exchange error, etc.).

add_action('auris_sso_login_failed', function (string $errorCode, string $errorMessage) {
    // $errorCode — machine-readable error code
    // $errorMessage — human-readable error description
 
    error_log('[Auris SSO] Login failed: [' . $errorCode . '] ' . $errorMessage);
});

auris_sso_before_redirect

Fires just before the plugin redirects the user to the Auris hosted login page. Allows modifying the login URL options.

add_filter('auris_sso_login_options', function (array $options): array {
    // Force Italian locale for all SSO logins from this site
    $options['locale'] = 'it';
    return $options;
});

Filter Hooks

auris_sso_map_role

Allows custom PHP logic for role mapping instead of (or in addition to) the settings table.

add_filter('auris_sso_map_role', function (string $wpRole, array $aurisRoles): string {
    // $wpRole    — role determined by the settings table (or default)
    // $aurisRoles — array of all Auris role names the user has
 
    if (in_array('billing_admin', $aurisRoles, true)) {
        return 'shop_manager'; // WooCommerce role
    }
 
    return $wpRole; // Fall through to the default
}, 10, 2);

auris_sso_user_data

Allows modifying the user data array before a WordPress user is created or updated.

add_filter('auris_sso_user_data', function (array $userData, array $aurisUser): array {
    // $userData  — array of wp_insert_user / wp_update_user data
    // $aurisUser — raw Auris user data
 
    // Example: set display_name to first + last
    $userData['display_name'] = trim(
        ($aurisUser['firstName'] ?? '') . ' ' . ($aurisUser['lastName'] ?? '')
    );
 
    return $userData;
}, 10, 2);

Troubleshooting

Redirect URI mismatch

The URI registered in the Auris Console must be character-for-character identical to the one configured in the plugin settings. Common causes:

• Trailing slash difference (/callback vs /callback/)
• http vs https
• A staging domain that is different from production

SSL required

Auris requires HTTPS for all redirect URIs in production. For local development, use a local SSL certificate or the http://localhost exception (consult your Auris plan documentation for this option).

Session not persisting after login

WordPress saves the session cookie to the site’s domain. If your site is behind a load balancer or reverse proxy, ensure the X-Forwarded-Proto header is forwarded and that is_ssl() returns true inside WordPress.

Add to wp-config.php if needed:

if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
    $_SERVER['HTTPS'] = 'on';
}

User login loop

If users are redirected back to the login page immediately after authenticating, check:

1. The WordPress site URL in Settings → General matches the URL the user is visiting.
2. The COOKIEPATH and COOKIE_DOMAIN constants in wp-config.php are not set to overly restrictive values.
3. The plugin’s Redirect URI matches the Auris Console registration exactly.

Users get the wrong WordPress role

Check the role mapping table in Settings → Auris SSO → Role Mapping. Roles are evaluated top-to-bottom. The first matching Auris role wins. If none match, the WordPress default role is used.

Related Pages

• PHP SDK — The underlying PHP library used by this plugin
• Hosted Login Guide — PKCE flow overview
• Enterprise SSO — SAML 2.0 and OIDC for B2B