Single Sign-On (SSO)

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

Supported Providers

QwikCa 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 QwikCa
IdP admin access — You need admin access to your identity provider

SAML 2.0 Configuration

Step 1: Get QwikCa SAML Details

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

Field	Value
ACS URL	`https://auth.QwikCa.example.com/saml/acs/{org-id}`
Entity ID	`https://QwikCa.example.com/saml/{org-id}`
Sign-on URL	`https://auth.QwikCa.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 QwikCa

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 QwikCa

OpenID Connect Configuration

Step 1: Create OIDC Application

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

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

Step 2: Configure QwikCa

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 QwikCa callback URL
Copy Client ID and Client Secret to QwikCa

User Provisioning

Just-in-Time (JIT) Provisioning

By default, users are created in QwikCa 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.QwikCa.example.com/scim/v2
- Bearer Token: Your generated token

SCIM supports:

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

Role Mapping

Map IdP groups or attributes to QwikCa roles:

// Role mapping configuration
{
  roleMapping: {
    // Map IdP groups to QwikCa 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:

QwikCa users revoke-sessions user@example.com

Troubleshooting

”Invalid SAML Response”

Common causes:

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

”User not found”

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

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

“Attribute mapping failed”

Verify your IdP is sending required attributes:

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

QwikCa 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 — QwikCa respects IdP MFA requirements
Monitor SSO logs — Review authentication events regularly
Test disaster recovery — Ensure you can access QwikCa 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

QwikCa sso add-bypass admin@example.com