Single Sign-On (SSO) - rizset Docs

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

Supported Providers

Virex 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:

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

SAML 2.0 Configuration

Step 1: Get Virex SAML Details

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

Field	Value
ACS URL	`https://auth.virex.example.com/saml/acs/{org-id}`
Entity ID	`https://virex.example.com/saml/{org-id}`
Sign-on URL	`https://auth.virex.example.com/saml/login/{org-id}`

Step 2: Configure Your IdP

Okta

In Okta Admin, go to Applications → Create App Integration
Select SAML 2.0
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
Add attribute statements:

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

Download the IdP metadata XML

Azure AD

In Azure Portal, go to Enterprise Applications → New Application
Select Create your own application
Choose Integrate any other application (Non-gallery)
Go to Single sign-on → SAML
Configure Basic SAML Configuration:
- Identifier (Entity ID): Your Entity ID
- Reply URL (ACS URL): Your ACS URL
- Sign on URL: Your Sign-on URL
Configure User Attributes & Claims:
- emailaddress → user.mail
- givenname → user.givenname
- surname → user.surname
Download Federation Metadata XML

Step 3: Upload IdP Metadata to Virex

Go to Settings → Security → SSO
Click Configure SAML
Upload your IdP metadata XML file
Click Save Configuration

Step 4: Test the Connection

Click Test SSO Connection
You’ll be redirected to your IdP
Authenticate with your IdP credentials
Verify you’re redirected back to Virex

OpenID Connect Configuration

Step 1: Create OIDC Application

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

Field	Value
Redirect URI	`https://auth.virex.example.com/oidc/callback/{org-id}`
Grant Type	Authorization Code
Response Type	code

Step 2: Configure Virex

Go to Settings → Security → SSO
Click Configure OIDC
Enter your IdP details:

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

Click Save Configuration

Google Workspace Example

Go to Google Cloud Console
Create a new OAuth 2.0 Client ID
Set authorized redirect URI to your Virex callback URL
Copy Client ID and Client Secret to Virex

User Provisioning

Just-in-Time (JIT) Provisioning

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

// Default JIT settings
{
  jitProvisioning: true,
  defaultRole: 'developer',
  autoJoinTeams: ['engineering']
}

SCIM Provisioning

For automatic user lifecycle management, enable SCIM:

Go to Settings → Security → SCIM
Generate a SCIM token
Configure your IdP with:
- SCIM Base URL: https://api.virex.example.com/scim/v2
- Bearer Token: Your generated token

SCIM supports:

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

Role Mapping

Map IdP groups or attributes to Virex roles:

// Role mapping configuration
{
  roleMapping: {
    // Map IdP groups to Virex roles
    groups: {
      'Engineering': 'developer',
      'DevOps': 'admin',
      'Management': 'viewer'
    },
    // Or map based on attributes
    attributes: {
      'department': {
        'Engineering': 'developer',
        'Operations': 'admin'
      }
    },
    // Default role if no mapping matches
    default: 'viewer'
  }
}

Enforcing SSO

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

Go to Settings → Security → SSO
Enable Require SSO for all users
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
    reauthForSensitive: true,
    // Idle timeout
    idleTimeout: '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:

virex users revoke-sessions user@example.com

Troubleshooting

”Invalid SAML Response”

Common causes:

Clock skew — Ensure IdP and Virex times are synchronized
Wrong ACS URL — Verify the URL matches exactly
Certificate expired — Update the IdP certificate in Virex

”User not found”

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

virex users create user@example.com --sso-only

“Attribute mapping failed”

Verify your IdP is sending required attributes:

virex sso debug --last-login user@example.com

This shows the raw SAML assertion or OIDC claims received.

Users can’t access after IdP changes

Clear the SSO cache:

virex sso clear-cache

Security Best Practices

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

Bypass Access

For emergency access when SSO is unavailable:

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

virex sso add-bypass admin@example.com