Single Sign-On (SSO) - Clearpoint Systems Docs

Single Sign-On (SSO) allows your team to authenticate with Clearpoint Systems Technology using your existing identity provider. This simplifies access management and improves security by centralizing authentication.

Supported Providers

Clearpoint supports SSO via SAML 2.0 and OpenID Connect (OIDC):

SAML 2.0

• Okta
• Azure Active Directory
• OneLogin
• PingIdentity
• JumpCloud
• Any SAML 2.0 compliant IdP

OpenID Connect

• Google Workspace
• Auth0
• Keycloak
• Any OIDC compliant provider

Prerequisites

Before configuring SSO:

1. Enterprise plan — SSO is available on Enterprise plans only
2. Verified domain — Your email domain must be verified in Clearpoint
3. IdP admin access — You need admin access to your identity provider

SAML 2.0 Configuration

Step 1: Get Clearpoint SAML Details

In the Clearpoint dashboard, go to Settings → Security → SSO and note:

Field	Value
ACS URL	https://auth.clearpointsystems.tech/saml/acs/{org-id}
Entity ID	https://clearpointsystems.tech/saml/{org-id}
Sign-on URL	https://auth.clearpointsystems.tech/saml/login/{org-id}

Step 2: Configure Your IdP

Okta

1. In Okta Admin, go to Applications → Create App Integration

2. Select SAML 2.0

3. Configure:

   • Single sign-on URL: Your ACS URL from Step 1
   • Audience URI: Your Entity ID from Step 1
   • Name ID format: EmailAddress
   • Application username: Email

4. Add attribute statements:

Name	Value
email	user.email
firstName	user.firstName
lastName	user.lastName

5. Download the IdP metadata XML

Azure AD

1. In Azure Portal, go to Enterprise Applications → New Application

2. Select Create your own application

3. Choose Integrate any other application (Non-gallery)

4. Go to Single sign-on → SAML

5. Configure Basic SAML Configuration:

   • Identifier (Entity ID): Your Entity ID
   • Reply URL (ACS URL): Your ACS URL
   • Sign on URL: Your Sign-on URL

6. Configure User Attributes & Claims:

   • emailaddress → user.mail
   • givenname → user.givenname
   • surname → user.surname

7. Download Federation Metadata XML

Step 3: Upload IdP Metadata to Clearpoint

1. Go to Settings → Security → SSO
2. Click Configure SAML
3. Upload your IdP metadata XML file
4. Click Save Configuration

Step 4: Test the Connection

1. Click Test SSO Connection
2. You’ll be redirected to your IdP
3. Authenticate with your IdP credentials
4. Verify you’re redirected back to Clearpoint

OpenID Connect Configuration

Step 1: Create OIDC Application

In your identity provider, create a new OIDC application with:

Field	Value
Redirect URI	https://auth.clearpointsystems.tech/oidc/callback/{org-id}
Grant Type	Authorization Code
Response Type	code

Step 2: Configure Clearpoint

1. Go to Settings → Security → SSO
2. Click Configure OIDC
3. Enter your IdP details:

Client ID: your-client-id
Client Secret: your-client-secret
Issuer URL: https://your-idp.com

4. Click Save Configuration

Google Workspace Example

1. Go to Google Cloud Console
2. Create a new OAuth 2.0 Client ID
3. Set authorized redirect URI to your Clearpoint callback URL
4. Copy Client ID and Client Secret to Clearpoint

User Provisioning

Just-in-Time (JIT) Provisioning

By default, users are created in Clearpoint when they first sign in via SSO:

# Default JIT settings
jit_provisioning: true
default_role: 'data_analyst'
auto_join_departments: ['operations']

SCIM Provisioning

For automatic user lifecycle management, enable SCIM:

1. Go to Settings → Security → SCIM
2. Generate a SCIM token
3. Configure your IdP with:
   • SCIM Base URL: https://api.clearpointsystems.tech/scim/v2
   • Bearer Token: Your generated token

SCIM supports:

• User creation — New IdP users are created in Clearpoint
• User updates — Profile changes sync automatically
• User deactivation — Removed IdP users lose Clearpoint access
• Group sync — IdP groups map to Clearpoint departments

Role Mapping

Map IdP groups or attributes to Clearpoint roles:

# Role mapping configuration
role_mapping:
  # Map IdP groups to Clearpoint roles
  groups:
    'Operations': 'operations_manager'
    'Finance': 'data_analyst'
    'Compliance': 'compliance_officer'
    'IT': 'system_administrator'
  # Or map based on attributes
  attributes:
    'department':
      'Operations': 'operations_manager'
      'Finance': 'data_analyst'
      'IT': 'system_administrator'
  # Default role if no mapping matches
  default: 'viewer'

Enforcing SSO

Once SSO is configured, you can enforce it for all users:

1. Go to Settings → Security → SSO
2. Enable Require SSO for all users
3. Optionally, allow password login for specific users (e.g., service accounts)

When enforced:

• Users must authenticate via SSO
• Password login is disabled
• Existing sessions remain valid until expiry

Session Management

Configure SSO session behavior:

session:
  # Session duration (max 24 hours with SSO)
  duration: '8h'
  # Require re-authentication for sensitive actions
  reauth_for_sensitive: true
  # Idle timeout
  idle_timeout: '1h'

Session Termination

When a user is deactivated in your IdP:

• With SCIM: Access is revoked immediately
• Without SCIM: Access is revoked at next session refresh (within 1 hour)

Force immediate session termination:

POST /api/v1/users/{user_id}/revoke-sessions

Troubleshooting

”Invalid SAML Response”

Common causes:

1. Clock skew — Ensure IdP and Clearpoint times are synchronized
2. Wrong ACS URL — Verify the URL matches exactly
3. Certificate expired — Update the IdP certificate in Clearpoint

”User not found”

If JIT provisioning is disabled, users must be pre-created:

POST /api/v1/users
{
  "email": "user@company.com",
  "sso_only": true
}

“Attribute mapping failed”

Verify your IdP is sending required attributes:

GET /api/v1/sso/debug?user=user@company.com

This shows the raw SAML assertion or OIDC claims received.

Users can’t access after IdP changes

Clear the SSO cache:

POST /api/v1/sso/clear-cache

Security Best Practices

1. Enable SCIM — Ensure deactivated users lose access immediately
2. Use short session durations — Reduce risk from compromised sessions
3. Require MFA at IdP — Clearpoint respects IdP MFA requirements
4. Monitor SSO logs — Review authentication events regularly
5. Test disaster recovery — Ensure you can access Clearpoint if IdP is down

Bypass Access

For emergency access when SSO is unavailable:

1. Designate bypass users in Settings → Security → SSO
2. These users can log in with email/password
3. Limit bypass users to essential personnel only

POST /api/v1/sso/bypass-users
{
  "email": "admin@company.com",
  "reason": "Emergency access"
}