User Story

As a service provider, I want to integrate PortaSwitch with two Keycloak SSO instances

• • one for customers
  • another for admin users

so that all stakeholders can securely access relevant services (CloudPBX portals, Admin UI, etc.) using a unified login experience, while maintaining strict role separation and security compliance.

Example of use

• Customer: Logs into the self-care portal to view billing details using credentials validated by the Customer Keycloak instance.
• PortaSwitch Administrator: Logs into the Admin UI to manage products and services, with authentication through a separate Admin Keycloak instance that enforces stricter access controls and policies.

Business model

Cloud PBX, UCaaS

Technology

Keycloak, Single-Sign-On (SSO), OAuth2.0, OpenID Connect (OIDC), Multi-Factor Authentication (MFA)

Current Solution

• Legacy authentication relies solely on passwords with optional MFA, leading to inconsistent enforcement.

• No centralized identity provider; fragmented systems increase vulnerability.

Stakeholders and their benefits

Cloud PBX and UCaaS users will use a single set of credentials to access multiple services

Use Cases

Use case #1: Enforce MFA for Self-Care

Roles:

• User: Employee of the Customer Alpha Corp

• Support: PortaOne Support Engineer

• Portal: UI frontend (customer self-care) using PortaSwitch API

• SSO System: External identity provider (Keycloak with Customer users)

Preconditions:

• CSP’s policy mandates MFA for all customer self-care users

• CSP uses SSO System supporting multi-factor authentication

• Customer "Alpha Corp" has an active CloudPBX subscription and access to customer self-care at https://selfcare.csp.com

• Employees of "Alpha Corp" exist in SSO System
• There is "ZZZPortaOne" customer in PortaSwitch

Use scenario #1.1: Customer Successfully Logs In via SSO

• Employee of Alpha Corp, Bob, navigates to https://selfcare.csp.com and chooses to log in with SSO
• Portal redirects to the SSO System

• Bob interacts with the SSO System by entering access details (e.g. login, email, phone number)

• SSO System initiates authentication via the Bob’s registered method (e.g. by sending a one-time code/link to the registered email/phone or prompting for biometric verification, e.g., FaceID/fingerprint)

• Bob completes the authentication step (e.g., clicks link, enters code)

• SSO System validates the response and grants access

• Bob is redirected to the Portal with authenticated session/token

• Bob configures their Cloud PBX environment by adding email addresses for extensions

Use scenario #1.2: Authentication Attempt Fails (alternative to #1.1)

• Bob interacts with the SSO System by entering access details (e.g. login, email, phone number)

• SSO System cannot verify the Bob’s identity (e.g., invalid code, expired link).

• SSO System returns an error

• Bob may restart the flow

Use scenario #1.3: Support Successfully Logs In with a Login and Password

• Support Engineer works on an issue and needs to access the customer self-care
• Support Engineer navigates to https://selfcare.csp.com
• Support Engineer enters a password for ZZZPortaOne customer and is successfully logged in
• Support Engineer checks the reported issue in the customer self-care

Use scenario #1.4: Adding a New Employee

• Bob is logged in to https://selfcare.csp.com
• Bob adds a new employee "john.smith@csp.com" who recently joined their company
• The new user's data (login, email, role) is provisioned to the SSO System
• The new employee, John Smith, navigates to https://selfcare.csp.com and chooses to log in with SSO
• Portal redirects to the SSO System

• John Smith interacts with the SSO System by entering access details (e.g. login, email)

• SSO System initiates authentication via the John’s registered method (e.g. by sending a one-time code/link to the registered email/phone or prompting for biometric verification, e.g., FaceID/fingerprint)

• John Smith completes the authentication step (e.g., clicks link, enters code)

• SSO System validates the response and grants access

• John Smith is redirected to the Portal with authenticated session/token

• John Smith configures their Cloud PBX environment by adding email addresses for extension

Use Case #2: Enforce Role-Based SSO for Admin UI Access

Roles:

• Administrator: CSP employee with elevated privileges

• Admin interface: PortaSwitch Admin UI (e.g., https://admin.csp.com)

• Support: PortaOne Support Engineer

• SSO System: External identity provider (Keycloak with Admin users)

Preconditions:

• Admin users are provisioned in the SSO System

• Admin Keycloak is configured with strict MFA

• Admin interface is integrated with Admin Keycloak (OIDC/OAuth2.0)

• There is porta-support for Admin access

Use Scenario #2.1: Admin Logs In Successfully

• Admin navigates to https://admin.csp.com and chooses to log in with SSO
• Admin interface redirects to the SSO System
• Admin interacts with Keycloak by entering access details
• SSO System initiates authentication via the Admin user's registered method (e.g. by sending a one-time code/link to the registered email/phone or prompting for biometric verification, e.g., FaceID/fingerprint)
• Admin completes the authentication step
• SSO System validates the response and grants access
• Admin is redirected to the Admin interface with authenticated session/token
• Admin interface gets needed details about the user (e.g. superuser=true or false) using the authenticated session/token
• Admin manages products and customers

Use Scenario #2.2: Admin Authentication Fails (alternative to #2.1)

• Same as #1.2 but with Keycloak with Admin users

Use scenario #2.3: Support Successfully Logs In with a Login and Password

• Support Engineer works on an issue and needs to access PortaSwitch Admin UI
• Support Engineer navigates to https://selfcare.csp.com
• Support Engineer enters a password for porta-support user and is successfully logged in
• Support Engineer checks the reported issue in the customer self-care

Wireframes

Non-functional requirements

• Security:
  • HTTPS to protects against token interception and MITM (man-in-the-middle) attacks
  • No logging of client secrets
  • Decode/validate tokens using Keycloak’s public key
  • Reference OpenID metadata for token verification

Peculiarities

• CloudPBX portal uses PortaBilling, PortaSIP, Call Control APIs
• CSP is not planning to use Resellers, Distributors or Representatives for now
• CSP does not require PortaBilling to grant access to Account API via SSO

Notes for Design

• The design must suggest a mechanism to synchronize records between PortaSwitch and SSO Systems
• CSP customers will have both customers and customer individuals to access the self-care portals
• Reference documentation provided by the CSP

Performance / Clustering, Geo Redundancy/ Dual-Version, Porter / Call Control API

• The integration with the SSO must remain functional in the standalone and dual-version modes

ESPF / Monitoring

Basic monitoring is required for the integration with SSO systems in order to:

• avoid de-synchronization between PortaBilling and SSO (Keycloak)
• make sure communication between PortaBilling and SSO (Keycloak) is happening in a timely manner
• avoid failed attempts to log in to PortaBilling via SSO