Setting Up Single Sign-On

Phaset supports Single Sign-On (SSO) via OpenID Connect (OIDC), allowing your users to authenticate with their existing corporate identity provider instead of using email-based authentication.

Supported Identity Providers

Phaset currently supports:

• Microsoft Azure Entra ID (formerly Azure Active Directory)
• Google Workspace (formerly G Suite)

Note

Your Phaset deployment uses a single SSO configuration. All users authenticate through the same identity provider, but can belong to different Phaset organizations within your deployment.

Prerequisites

Before setting up SSO, ensure you have:

• Admin access to your identity provider (Azure Entra ID or Google Workspace)
• HTTPS enabled on your Phaset domain (required for OIDC)
• Your Phaset instance URL (e.g., https://phaset.yourcompany.com)

Configuration Overview

Setting up SSO involves two parts:

1. Register Phaset in your identity provider - Create an OAuth application and obtain credentials
2. Configure Phaset with SSO settings - Add credentials to your phaset.config.json

Azure Entra ID Setup

1. Register Application in Azure

   Go to the Azure Portal and navigate to Azure Active Directory → App Registrations.

   Click New registration and configure:

   • Name: Phaset SSO (or your preferred name)
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI:
     • Platform: Web
     • URI: https://your-phaset-domain.com/auth/sso/callback/azure

   Click Register.

2. Note Your Application IDs

   After registration, you’ll see the application overview page. Copy these values:

   • Application (client) ID - You’ll use this as clientId
   • Directory (tenant) ID - You’ll use this as tenantId

3. Create Client Secret

   In your app registration, go to Certificates & secrets.

   Click New client secret:

   • Description: Phaset SSO Secret
   • Expires: Choose an expiration period

   Click Add.

   Caution

   Copy the Value immediately and store it securely. You won’t be able to see it again. This is your clientSecret.

4. Configure API Permissions

   Go to API permissions in your app registration.

   Click Add a permission → Microsoft Graph → Delegated permissions.

   Add these permissions:

   • openid
   • profile
   • email

   Click Grant admin consent for [Your Organization] to approve these permissions.

5. Configure Phaset

   Add the SSO configuration to your phaset.config.json:

   {
     "sso": {
       "enabled": true,
       "provider": "azure",
       "tenantId": "your-tenant-id-from-step-2",
       "clientId": "your-client-id-from-step-2",
       "clientSecret": "your-client-secret-from-step-3",
       "redirectUri": "https://your-phaset-domain.com/auth/sso/callback/azure",
       "scopes": ["openid", "profile", "email"]
     }
   }

   Restart Phaset for changes to take effect.

Testing Azure SSO

Navigate to https://your-phaset-domain.com/auth/sso/azure in your browser. You should be redirected to the Microsoft login page. After authenticating with your Azure credentials, you’ll be redirected back to Phaset and logged in.

Google Workspace Setup

1. Create OAuth Client

   Go to the Google Cloud Console.

   Select your project (or create a new one), then navigate to APIs & Services → Credentials.

2. Configure OAuth Consent Screen

   If you haven’t configured the consent screen yet, click Configure Consent Screen:

   • User Type: Choose Internal (for Google Workspace users only) or External
   • App name: Phaset
   • User support email: Your support email address
   • Developer contact information: Your email address

   Under Scopes, add:

   • openid
   • profile
   • email

   Click Save and Continue through the remaining steps.

3. Create OAuth 2.0 Client ID

   Back in Credentials, click Create Credentials → OAuth 2.0 Client ID.

   Configure:

   • Application type: Web application
   • Name: Phaset SSO
   • Authorized redirect URIs: Add https://your-phaset-domain.com/auth/sso/callback/google

   Click Create.

4. Note Your Credentials

   Copy these values from the credential details:

   • Client ID - You’ll use this as clientId
   • Client Secret - You’ll use this as clientSecret

5. Configure Phaset

   Add the SSO configuration to your phaset.config.json:

   {
     "sso": {
       "enabled": true,
       "provider": "google",
       "clientId": "your-client-id.apps.googleusercontent.com",
       "clientSecret": "your-client-secret",
       "redirectUri": "https://your-phaset-domain.com/auth/sso/callback/google",
       "scopes": ["openid", "profile", "email"]
     }
   }

   Restrict to Your Domain

   To only allow users from your Google Workspace domain, add:

   "hostedDomain": "yourcompany.com"

   This ensures users with personal Google accounts cannot sign in.

   Restart Phaset for changes to take effect.

Testing Google SSO

Navigate to https://your-phaset-domain.com/auth/sso/google in your browser. You should be redirected to the Google login page. After authenticating with your Google credentials, you’ll be redirected back to Phaset and logged in.

Configuration Methods

Like other Phaset settings, SSO can be configured via environment variables or CLI flags instead of the config file.

Environment Variables

Azure Entra ID:

SSO_ENABLED=true
SSO_PROVIDER=azure
SSO_TENANT_ID=your-tenant-id
SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret
SSO_REDIRECT_URI=https://your-phaset-domain.com/auth/sso/callback/azure
SSO_SCOPES=openid,profile,email

Google Workspace:

SSO_ENABLED=true
SSO_PROVIDER=google
SSO_CLIENT_ID=your-client-id.apps.googleusercontent.com
SSO_CLIENT_SECRET=your-client-secret
SSO_REDIRECT_URI=https://your-phaset-domain.com/auth/sso/callback/google
SSO_SCOPES=openid,profile,email
SSO_HOSTED_DOMAIN=yourcompany.com  # Optional

CLI Flags

phaset start \
  --ssoEnabled \
  --ssoProvider azure \
  --ssoTenantId your-tenant-id \
  --ssoClientId your-client-id \
  --ssoClientSecret your-secret \
  --ssoRedirectUri https://your-phaset-domain.com/auth/sso/callback/azure \
  --ssoScopes "openid,profile,email"

User Management

User Provisioning Required

Unless you have allowed self-sign up, users must be provisioned in Phaset before they can log in via SSO. This can be done through:

• SCIM provisioning (recommended for automated user management)
• Manual user creation in the Phaset UI

When a user signs in via SSO:

1. User is redirected to the identity provider login page
2. User authenticates with their corporate credentials
3. Identity provider sends authentication data back to Phaset
4. Phaset verifies the user exists and creates a session
5. User is logged into Phaset

Troubleshooting

”Redirect URI mismatch” Error

Cause: The redirect URI in your identity provider doesn’t exactly match your Phaset configuration.

Solution:

• Verify both URIs match exactly (check for trailing slashes)
• Ensure you’re using https:// in production
• For Azure: Check the redirect URI in Authentication settings
• For Google: Check Authorized redirect URIs in OAuth client

”Invalid state parameter” Error

Cause: The state token has expired or the user used browser back/forward buttons.

Solution:

• State tokens expire after 5 minutes
• Have the user restart the login process
• Don’t use browser navigation during SSO flow

”User not found” After Successful Authentication

Cause: The user doesn’t exist in Phaset.

Solution:

• Provision users via SCIM or manually create them
• Verify the email address matches between identity provider and Phaset

SSO Endpoint Returns 404

Cause: SSO is not enabled or Phaset hasn’t restarted after configuration.

Solution:

• Verify sso.enabled is true in your config
• Restart Phaset: phaset start
• Check the correct URL: /auth/sso/azure or /auth/sso/google

Client Secret Expired (Azure)

Cause: Azure client secrets expire based on the period you selected.

Solution:

• Go to Certificates & secrets in Azure Portal
• Create a new client secret
• Update clientSecret in your Phaset configuration
• Restart Phaset

Personal Google Accounts Can Sign In

Cause: The hostedDomain restriction is not configured.

Solution:

• Add "hostedDomain": "yourcompany.com" to your SSO config
• Restart Phaset
• Domain must exactly match your Google Workspace domain

Questions and Answers

Can I use both Azure and Google SSO?

No, each Phaset deployment supports one identity provider. Choose the provider that matches your organization’s identity management system.

What happens if the identity provider goes down?

Users won’t be able to log in until the service is restored. Consider having a backup authentication method (like email-based auth) enabled for critical administrators.

Do sessions stay active if I switch identity providers?

No, existing sessions will be invalidated when you switch providers. Users will need to sign in again with the new provider.

Can I test SSO without affecting production users?

Yes, configure SSO in a test/staging Phaset instance first. Once verified, apply the same configuration to production.

How long do SSO sessions last?

Session duration is controlled by Phaset’s JWT settings (default 60 minutes, with automatic refresh). When tokens expire, users are redirected to SSO for seamless re-authentication if still logged into their identity provider.

Next Steps

• Set up SCIM provisioning for automated user management
• Configure Phaset for production deployment
• Learn about Phaset security best practices