Z8 Docs
Admin Guide

Social OAuth

Configure organization-specific social login providers for single sign-on

Enterprise organizations can configure their own OAuth providers to enable branded sign-in. Users sign in with the provider connected to that organization's OAuth application.

Benefits of Organization OAuth

BenefitDescription
Branded LoginUsers see your organization's name during sign-in
Access ControlRestrict sign-in to your organization's domain
Audit TrailAll authentication goes through your OAuth app
SSO IntegrationWorks with existing identity management

Accessing Social OAuth Settings

  1. Go to Settings in the sidebar
  2. Open Enterprise and go to the custom domain and branding area
  3. View the Social Login Providers management table

OAuth credentials are configured per organization in product settings. Do not treat them as tenant-wide environment variables.

Supported Providers

Google OAuth Setup

  1. Go to Google Cloud Console
  2. Create or select a project
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth client ID
  5. Select Web application
  6. Add authorized redirect URI: 
    https://your-z8-domain.com/api/auth/callback/social-org/google
  7. Copy the Client ID and Client Secret

Configuration in Z8

  1. Click Add Provider > Google
  2. Enter your Client ID and Client Secret
  3. Click Save

Microsoft Azure AD Setup

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory > App registrations
  3. Click New registration
  4. Set redirect URI: 
    https://your-z8-domain.com/api/auth/callback/social-org/microsoft
  5. Under Certificates & secrets, create a new client secret
  6. Copy the Application (client) ID and secret value

Configuration in Z8

  1. Click Add Provider > Microsoft
  2. Enter your Client ID and Client Secret
  3. Click Save

GitHub OAuth Setup

  1. Go to GitHub Developer Settings
  2. Click OAuth Apps > New OAuth App
  3. Set Authorization callback URL: 
    https://your-z8-domain.com/api/auth/callback/social-org/github
  4. Register the application
  5. Generate a new client secret
  6. Copy the Client ID and Client Secret

Configuration in Z8

  1. Click Add Provider > GitHub
  2. Enter your Client ID and Client Secret
  3. Click Save

LinkedIn OAuth Setup

  1. Go to LinkedIn Developers
  2. Create a new application
  3. Under Auth, add redirect URL: 
    https://your-z8-domain.com/api/auth/callback/social-org/linkedin
  4. Request the r_emailaddress and r_liteprofile permissions
  5. Copy the Client ID and Client Secret

Configuration in Z8

  1. Click Add Provider > LinkedIn
  2. Enter your Client ID and Client Secret
  3. Click Save

Apple Sign-In Setup

Apple requires additional configuration:

  1. Go to Apple Developer Portal
  2. Create a new Services ID for Sign in with Apple
  3. Configure the service with your domain
  4. Create a new Key for Sign in with Apple
  5. Download the .p8 private key file

Required Information

  • Team ID: Found in your Apple Developer account
  • Key ID: The ID of the key you created
  • Private Key: Contents of the .p8 file

Configuration in Z8

  1. Click Add Provider > Apple
  2. Enter:
    • Client ID (Services ID)
    • Team ID
    • Key ID
    • Private Key (paste full contents)
  3. Click Save

Apple Private Key

The private key is only downloadable once from Apple. Store it securely.

Redirect URIs must match exactly

Register the callback URL for the exact domain your users sign in through. If you use multiple environments or custom domains, add the matching redirect URI for each one.

Managing Providers

The current UI lets organization admins:

  • Add a provider with org-specific credentials
  • Edit an existing provider
  • Remove a provider
  • Mark an existing provider active or inactive while editing it

The provider table can show status metadata such as Not Tested, Working, or Error, but the current product should not be treated as offering a full end-user configuration test workflow from this page.

User Experience

Login Flow

When an organization-specific provider is configured and active:

  1. User visits the organization's login page
  2. Clicks "Sign in with [Provider]"
  3. Redirected to provider with your org's branding
  4. User authenticates with their account
  5. Redirected back to Z8
  6. Account linked or created automatically

Account Linking

ScenarioBehavior
New user, new emailNew account created
Existing user, same emailAccount linked automatically
Existing user, different emailUser prompted to link accounts

Security Features

PKCE (Proof Key for Code Exchange)

All OAuth flows use PKCE to prevent authorization code interception attacks.

State Signing

OAuth state is signed with HMAC to prevent CSRF attacks.

Nonce Validation

OIDC providers include nonce validation to prevent replay attacks.

OAuth state is stored in secure, httpOnly cookies during the flow, while provider credentials remain stored as organization-scoped secrets in Z8.

Edit Configuration

  1. Open the provider row
  2. Click Edit
  3. Update the client ID, secret, or provider-specific values
  4. Save the changes

Delete Provider

  1. Open the provider row
  2. Click Delete
  3. Confirm deletion
  4. The custom provider is removed from the organization

User Impact

Deleting a provider doesn't affect users who have already linked accounts. They can still sign in with other methods or re-link when the provider is re-added.

Domain Restrictions

For additional security, restrict which email domains can sign in:

  1. Go to Settings > Enterprise > Domains
  2. Add your organization's email domain(s)
  3. Only users with matching email domains can sign in via OAuth

Troubleshooting

"Invalid redirect URI"

  • Ensure the redirect URI in your OAuth app matches exactly
  • Check for trailing slashes
  • Verify the domain is correct

"Client ID not found"

  • Double-check the Client ID is entered correctly
  • Ensure the OAuth app is not deleted or disabled

"Invalid client secret"

  • Regenerate the secret in the provider's console
  • Update the secret in Z8 settings
  • Some providers (Microsoft) require periodic secret rotation

"User not authorized"

  • For Microsoft: Check the user is in the tenant
  • For Google: Verify domain restrictions
  • Check if the email domain is allowed

Saved configuration still fails during sign-in

  • Check the redirect URI and provider credentials again
  • Confirm the provider is active in the organization settings
  • Verify the callback is registered for the exact domain your users sign in through

Webhooks

Configure webhooks to receive real-time notifications when events occur in Z8

Conditional Access Policies

Configure fine-grained access controls based on user context, location, and device

On this page

Benefits of Organization OAuthAccessing Social OAuth SettingsSupported ProvidersGoogle OAuth SetupConfiguration in Z8Microsoft Azure AD SetupConfiguration in Z8GitHub OAuth SetupConfiguration in Z8LinkedIn OAuth SetupConfiguration in Z8Apple Sign-In SetupRequired InformationConfiguration in Z8Managing ProvidersUser ExperienceLogin FlowAccount LinkingSecurity FeaturesPKCE (Proof Key for Code Exchange)State SigningNonce ValidationSecure Cookie StorageEdit ConfigurationDelete ProviderDomain RestrictionsTroubleshooting"Invalid redirect URI""Client ID not found""Invalid client secret""User not authorized"Saved configuration still fails during sign-in