Self-Service Admin Portals

// Generate portal link for customer's IT admin
const portalLink = await $.Organization.getAdminPortal(orgId, {
  feature: 'sso' // or 'directory', 'audit-logs'
})

await $.Email.send({
  to: '[email protected]',
  subject: 'Configure SSO for your team',
  template: 'admin-portal-invitation',
  data: { portalLink }
})

// IT admin opens link and configures SSO themselves
// No developer or support engineer involvement needed

// User clicks "Configure SSO" in your app
on($.Button.clicked, async ({ button, organization }) => {
  if (button.id === 'configure-sso') {
    // Platform generates portal link automatically
    const portal = await $.Organization.getAdminPortal(organization.id, {
      feature: 'sso',
      returnUrl: 'https://app.yourcompany.com/settings/sso'
    })

    // Open in new window or iframe
    window.open(portal.url)
  }
})

// IT admin in portal:
// 1. Selects identity provider (Okta, Entra, etc.)
// 2. Enters IdP metadata URL or uploads XML
// 3. Verifies company domains
// 4. Tests SSO connection
// 5. Activates for their organization

// Your app receives event when complete
on($.SSO.configured, async ({ organization, connectionType }) => {
  console.log(`SSO configured for ${organization.name} using ${connectionType}`)

  // Update UI to show SSO is active
  await $.Notification.send({
    to: organization.adminEmail,
    message: `SSO is now active for ${organization.name}`
  })
})

// Generate directory sync portal
const portal = await $.Organization.getAdminPortal(orgId, {
  feature: 'directory',
  returnUrl: 'https://app.yourcompany.com/settings/directory'
})

// IT admin configures:
// 1. Select directory provider (Okta, Entra, Google, etc.)
// 2. Configure SCIM endpoint and credentials
// 3. Map attributes (optional)
// 4. Test connection
// 5. Activate directory sync

// Your app receives events automatically
on($.Directory.activated, async ({ organization, directory }) => {
  console.log(`Directory sync activated for ${organization.name}`)

  // Platform automatically syncs users
  // No code needed - provisioning events fire automatically
})

const portal = await $.Organization.getAdminPortal(orgId, {
  feature: 'audit-logs'
})

// IT admin can configure:
// - Stream to SIEM (Splunk, Datadog, etc.)
// - Export to S3
// - Retention policies
// - Event filters

// React component example
export function SSOConfigurationPage({ organization }) {
  const [portalUrl, setPortalUrl] = useState(null)

  useEffect(() => {
    async function loadPortal() {
      const response = await fetch(`/api/admin-portal/sso/${organization.id}`)
      const { url } = await response.json()
      setPortalUrl(url)
    }
    loadPortal()
  }, [organization.id])

  return (
    <div className="admin-portal-container">
      <h1>Configure Single Sign-On</h1>
      <p>Allow your team to sign in using your company's identity provider.</p>

      {portalUrl && (
        <iframe
          src={portalUrl}
          width="100%"
          height="800"
          frameBorder="0"
          style={{ border: 'none' }}
        />
      )}
    </div>
  )
}

// Portal opened
on($.AdminPortal.opened, async ({ organization, feature, userId }) => {
  console.log(`${userId} opened ${feature} portal for ${organization.name}`)
})

// Configuration completed
on($.AdminPortal.completed, async ({ organization, feature }) => {
  console.log(`${feature} configured for ${organization.name}`)

  // Send notification
  await $.Notification.send({
    to: organization.admins,
    message: `${feature} has been configured and is now active`
  })
})

// Configuration failed
on($.AdminPortal.failed, async ({ organization, feature, error }) => {
  console.log(`${feature} configuration failed for ${organization.name}:`, error)

  // Alert support team if needed
  if (error.requiresSupport) {
    await $.Alert.send({
      type: 'support',
      message: `Configuration help needed for ${organization.name}`,
      details: { feature, error }
    })
  }
})

// Only organization admins can generate portal links
on($.API.request, async ({ path, user }) => {
  if (path.startsWith('/admin-portal')) {
    // Platform checks automatically
    const isAdmin = await $.User.hasRole(user.id, 'admin')

    if (!isAdmin) {
      throw new Error('Only administrators can access admin portals')
    }
  }
})

// Or use platform permission check
const canAccessPortal = await $.User.can(user, 'configure', $.Organization)

// Configure portal branding via platform settings
await $.Organization.update(orgId, {
  portalBranding: {
    logo: 'https://yourcompany.com/logo.png',
    primaryColor: '#FF6B35',
    companyName: 'Your Company',
    supportEmail: '[email protected]'
  }
})

// Platform applies branding to all admin portals automatically

// After organization reaches certain size
on($.User.created, async ({ organization }) => {
  const userCount = await $.User.count({ organizationId: organization.id })

  if (userCount === 10 && !organization.ssoConfigured) {
    // Suggest SSO configuration
    await $.Notification.send({
      to: organization.adminEmail,
      type: 'feature_recommendation',
      title: 'Consider enabling SSO',
      message: 'Your team has grown to 10 users. SSO streamlines authentication and improves security.',
      action: {
        label: 'Configure SSO',
        url: await $.Organization.getAdminPortal(organization.id, { feature: 'sso' })
      }
    })
  }
})

// In your app's settings page
function SSOSettings({ organization }) {
  return (
    <div>
      <h2>Single Sign-On</h2>

      {!organization.ssoConfigured ? (
        <div className="feature-pitch">
          <h3>Enable SSO for your team</h3>
          <ul>
            <li>✓ Centralized user management</li>
            <li>✓ Enforce MFA and security policies</li>
            <li>✓ Automatic onboarding/offboarding</li>
            <li>✓ Meet compliance requirements</li>
          </ul>

          <p>Setup takes 10-15 minutes. No technical expertise required.</p>

          <button onClick={openAdminPortal}>
            Configure SSO
          </button>
        </div>
      ) : (
        <div className="feature-active">
          <p>✓ SSO is active ({organization.ssoType})</p>
          <button onClick={openAdminPortal}>
            Manage SSO Settings
          </button>
        </div>
      )}
    </div>
  )
}

// Show relevant documentation based on IdP choice
const providerDocs = {
  'Okta': '/docs/sso/okta',
  'Microsoft Entra': '/docs/sso/azure',
  'Google Workspace': '/docs/sso/google'
}

// Display in your UI or portal can include links

// Platform handles security automatically
const portal = await $.Organization.getAdminPortal(orgId, {
  feature: 'sso',
  expiresIn: '24h',
  singleUse: true // Optional: invalidate after first use
})

// Portal engagement metrics
const metrics = await $.Analytics.get({
  metric: 'admin_portal_usage',
  period: 'last_30_days'
})

console.log({
  portalsOpened: metrics.opened,
  configurationscompleted: metrics.completed,
  completionRate: (metrics.completed / metrics.opened * 100).toFixed(1) + '%',
  avgTimeToComplete: metrics.avgCompletionTime
})

// Alert on failures
on($.AdminPortal.failed, async ({ organization, feature, error }) => {
  await $.Alert.send({
    type: 'product',
    message: `Portal failure for ${organization.name}`,
    details: { feature, error }
  })
})