SureTax Portal SSO Integration

Seamless Single Sign-On between your Customer Portal and SureTax using OpenID Connect (OIDC)

OpenID Connect Authorization Code Flow Auto-Provisioning Enterprise IdP Support

Introduction

This guide describes how to integrate Single Sign-On (SSO) between your Customer Portal and the SureTax Portal using the OpenID Connect (OIDC) protocol. SSO integration enables your users to access SureTax Portal seamlessly using their existing corporate credentials — eliminating the need for separate SureTax logins, reducing credential management overhead, and improving security posture.

With SSO enabled, users authenticate once through your organization's Identity Provider (IdP) and are automatically granted access to the SureTax Portal without a second login prompt. The integration leverages standard OIDC flows, making it compatible with all major identity providers.

🔑

Single Sign-On

Users sign in once and access both portals without re-entering credentials.

🛡️

Centralized Security

Authentication is centralized through your IdP with MFA and session management.

⚡

Auto-Provisioning

Optionally create SureTax accounts automatically on first login.

🌐

Universal IdP Support

Azure AD, Okta, Ping Identity, Auth0, and any OIDC-compliant provider.

Business Requirement

The business objective is to enable seamless Single Sign-On (SSO) between the Customer Portal and the SureTax Portal using the OpenID Connect protocol. This integration will streamline user authentication, leveraging the client's Identity Provider (IdP) to pass essential user claims, including the email address (user ID).

Key benefits of SSO integration:

SSO Flow

High-Level Diagram

The following diagram illustrates the high-level SSO authentication flow between the Customer Portal, the Identity Provider (IdP), and the SureTax Portal:

High-level SSO flow diagram showing the authentication flow between Customer Portal, IdP, and SureTax Portal
Figure 1 — High-level SSO authentication flow

The SSO flow follows the OpenID Connect Authorization Code grant type. The customer's IdP acts as the authentication authority, and the SureTax Portal acts as a relying party (RP) that trusts the IdP to authenticate users and provide identity claims.

Step-by-Step Flow

StepDescription
1User accesses the Customer Portal and initiates login.
2Customer Portal redirects the user to the Identity Provider (IdP) for authentication.
3User authenticates with the IdP using their credentials (password, MFA, biometrics, etc., as configured by the customer's IdP policy).
4IdP generates an authentication token (authorization code) and redirects the user back to the Customer Portal via the Redirect URI.
5Customer Portal receives the token and sends a request to the SureTax Portal.
6SureTax Portal validates the request with the IdP and retrieves user claims via token exchange.
7On successful validation, SureTax Portal grants the user access and establishes a session.

End-to-End Flow

The following diagram shows the detailed end-to-end SSO flow including token exchange and session establishment:

End-to-end SSO flow diagram showing detailed token exchange and session establishment
Figure 2 — Detailed end-to-end SSO flow with token exchange
📝 Note
The SureTax Portal uses the Authorization Code flow (not Implicit), which is the recommended OIDC flow for server-side web applications. This ensures that tokens are exchanged securely on the back channel and are never exposed to the user's browser.

Customer-Side Changes

The customer is responsible for configuring their Identity Provider and their Customer Portal to support the SSO integration with SureTax.

Prerequisites

Before starting the SSO integration, ensure the following:

Changes Expected from Customer Side

  1. Identity Provider Configuration — Configure your IdP to include the SureTax Portal as a trusted application, providing necessary claims and ensuring secure token issuance.
  2. SSO Testing — Before going live, configure the SureTax SSO URL on your portal and participate in thorough testing to ensure the SSO integration works seamlessly and securely.

Step 1: Information from SureTax

The following information is provided by the SureTax team to the customer. Use these values when configuring the SureTax client application registration in your IdP:

InformationValue
Application NameSureTax
Redirect URIhttps://{SureTaxDomain}/SureTax/signin-oidc-{providerid}
📝 Note
The {SureTaxDomain} and {providerid} placeholders will be replaced with actual values provided by your Wolters Kluwer implementation team during the SSO setup process.

Step 2: Information from Customer

The following information must be provided by the customer to the SureTax team to complete the IdP integration configuration on the SureTax side:

InformationDescription
Client IDA unique identifier assigned to the SureTax Portal client application in the customer's IdP for SSO integration purposes.
Client SecretClient secret of the SureTax Portal client application.
IdP MetadataThe configuration details of the IdP, including endpoints for authorization, token, and user info services. Typically provided as a well-known OIDC discovery URL (e.g., https://your-idp.com/.well-known/openid-configuration).
User ClaimsThe claim names used by your IdP for the following attributes (see details below).
Grant TypeAuthorization Code
Auth Provider / ProtocolOIDC (OpenID Connect)

Required and Optional Claims

The following claims should be configured in your IdP's token issuance policy for the SureTax client application:

ClaimRequired?Description
User EmailRequiredThe user's email address. This serves as the unique user identifier in SureTax.
First NameConditionalRequired if SureTax should automatically create user accounts; otherwise optional.
Last NameConditionalRequired if SureTax should automatically create user accounts; otherwise optional.
Account NameConditionalRequired if SureTax should automatically create accounts; otherwise optional.
Org CodeConditionalRequired if SureTax should automatically create accounts; otherwise optional.
Notification EmailOptionalIf not supplied, the user email will be used for notifications.

Step 3: How to Integrate

Once SSO configuration is completed on both the customer side and the SureTax side, perform the following steps to activate the integration:

  1. Add the SureTax SSO URL to the customer portal:
    https://{SureTaxDomain}/SureTax/SSO/ExternalLogin/{ProviderId}
  2. Initiate SSO — The SSO process begins when a user clicks a link or button in the Customer Portal that navigates to the SureTax SSO URL.
  3. Automatic redirect — After authentication with the IdP, users are automatically redirected to the SureTax Portal with an active session.
💡 Tip
Most customers implement this as a "Launch SureTax" button or menu item within their existing portal. The user clicks the link, and if they are already authenticated with the IdP (active IdP session), the redirect to SureTax is seamless — no additional login prompt is shown.

SureTax-Side Changes

Integration with Customer IdP

Integration with the customer's IdP in the SureTax Portal begins once the SureTax team receives the following from the customer:

The SureTax team configures the IdP as a trusted external authentication provider within the SureTax Portal. This is a one-time setup performed by Wolters Kluwer during the implementation process.

Account & User Provisioning

SureTax supports two provisioning models for SSO users:

Pre-Provisioned Users

Manual Setup

User accounts are created in SureTax before the first SSO login. SureTax matches the email claim from the IdP token to the existing user record.

  • Minimum claim: User email only
  • Best for: Organizations that prefer to control user access and role assignments directly in SureTax

Auto-Provisioned (JIT)

Just-in-Time

SureTax automatically creates user accounts and (optionally) parent accounts the first time a user logs in via SSO.

  • Best for: Organizations with large or frequently changing user bases
  • Minimizes manual user management in SureTax

Claims Required for Account Creation

InformationDescriptionNote
Account NameName of the parent account in SureTax platform.Required
Organization CodeUnique identifier for the customer account.Required
Notification EmailEmail address of the account owner.Optional — if not available, user email will be used

Claims Required for User Creation

InformationDescriptionNote
Username / EmailEmail address of the user.Required
First NameFirst name of the user.Required
Last NameLast name of the user.Required

Security Considerations

The SSO integration between the Customer Portal and SureTax Portal follows security best practices:

ConsiderationDetails
ProtocolOpenID Connect (OIDC) over TLS 1.2+. All communication is encrypted in transit.
Grant TypeAuthorization Code flow — tokens are exchanged on the back channel, never exposed to the browser.
Token ValidationSureTax validates all tokens against the IdP's signing keys and verifies issuer, audience, and expiration claims.
Session ManagementSureTax establishes its own session after successful SSO authentication. Session lifetime is configurable.
MFA SupportMFA is enforced by the customer's IdP. SureTax does not impose additional MFA requirements for SSO users since authentication is delegated to the IdP.
Secret ManagementClient secrets are stored securely by both parties and should be rotated according to your organization's security policies.
🔒 Security Best Practice
Rotate client secrets periodically and use your IdP's certificate rotation capabilities. Ensure all redirect URIs are registered with exact-match validation to prevent open-redirect attacks.

Troubleshooting

Common SSO integration issues and their resolutions:

IssuePossible CauseResolution
User redirected to IdP login page repeatedly Redirect URI mismatch between SureTax configuration and IdP registration. Verify the Redirect URI in your IdP matches exactly: https://{SureTaxDomain}/SureTax/signin-oidc-{providerid}
"Unauthorized" error after authentication Client ID or Client Secret mismatch. Verify the Client ID and Client Secret provided to SureTax match the values in your IdP's application registration.
User authenticated but not found in SureTax User has not been pre-provisioned and auto-provisioning is not enabled. Either create the user in SureTax before their first login, or enable auto-provisioning and ensure the required claims are included in the token.
Claims not received by SureTax Token issuance policy does not include the required claims for the SureTax client application. Review your IdP's token configuration and ensure the email, first name, last name (and account claims if using auto-provisioning) are included.
SSO works in test but fails in production Different IdP endpoints or client credentials between environments. Confirm that the production IdP discovery URL, Client ID, and Client Secret have been provided to the SureTax team for the production environment.

Implementation Timeline

A typical SSO integration follows this timeline:

PhaseDurationActivities
Kickoff Week 1 SureTax provides Redirect URI and Application Name. Customer initiates IdP registration.
Configuration Exchange Week 1–2 Customer provides Client ID, Client Secret, IdP metadata, and claim mappings to SureTax. SureTax configures the IdP integration.
Testing Week 2–3 Joint testing in the SureTax sandbox environment. Validate authentication flow, claim mapping, and user provisioning.
Go-Live Week 3–4 Production configuration, final validation, and SSO activation.
💡 Tip
The actual timeline depends on the customer's internal change management processes and IdP configuration lead times. Most SSO integrations are completed within 2–4 weeks.

Summary

SureTax Portal SSO integration provides seamless, secure access to the SureTax Portal using your organization's existing identity infrastructure. By leveraging OpenID Connect, the integration ensures compatibility with all major identity providers while maintaining enterprise-grade security standards.

ItemDetails
ProtocolOpenID Connect (OIDC)
Grant TypeAuthorization Code
Supported IdPsAzure AD (Entra ID), Okta, Ping Identity, Auth0, and any OIDC-compliant provider
User ProvisioningPre-provisioned or auto-provisioned (just-in-time)
Required ClaimsUser email (minimum); first name, last name, account name, org code for auto-provisioning
Typical Timeline2–4 weeks from kickoff to go-live

For questions or to initiate SSO integration, contact your Wolters Kluwer implementation team.