Getting Started with Aeion Identity & Security

Navigate: Identity & Security → OAuth Connections → Add Provider

Google OAuth:

```bash # Create OAuth 2.0 Client ID in Google Cloud Console # Authorized redirect URI: https://your-domain.com/api/auth/oauth/google/callback

# Set environment variables GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxx ```

GitHub OAuth:

```bash # Create OAuth App in GitHub Settings # Authorization callback URL: https://your-domain.com/api/auth/oauth/github/callback

GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ```

Microsoft Entra ID (OIDC):

```bash # Register app in Azure Portal # Redirect URI: https://your-domain.com/api/auth/oauth/microsoft/callback

MICROSOFT_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx MICROSOFT_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ```

Generic OIDC (Okta, Auth0, etc.):

bash OIDC_CLIENT_ID=your-client-id OIDC_CLIENT_SECRET=your-client-secret OIDC_AUTHORIZE_URL=https://your-idp.com/oauth2/v1/authorize OIDC_TOKEN_URL=https://your-idp.com/oauth2/v1/token OIDC_USERINFO_URL=https://your-idp.com/oauth2/v1/userinfo

The OAuth pipeline handles:

• PKCE (RFC 7636) — S256 code challenge on every authorization request
• Token encryption — refresh tokens encrypted with a dedicated key before storage
• Token refresh — automatic re-encryption on token rotation
• Short-lived state store — 10-minute expiry on OAuth state/callback tokens

Navigate: Identity & Security → Security Overview → Require MFA

Admin policy configuration:

typescript // MFA enforcement policy (per-tenant) { requiredForRoles: ["admin", "superadmin"], // MFA required for these roles requiredForAllUsers: false, // Or force all users allowedMethods: ["totp", "webauthn"], // TOTP and/or WebAuthn backupCodesRequired: true, // Must set up backup codes enforceOnNextLogin: true, // Users prompted on next login }

TOTP setup:

A user starts MFA setup from their profile and receives:

{ "secret": "JBSWY3DPEHPK3PXP", // Base32-encoded TOTP secret "qrCodeUrl": "otpauth://totp/AeionOS:user@example.com?secret=...&issuer=AeionOS", "backupCodes": ["A1B2C3D4", "E5F6G7H8", ...] // 10 one-time codes }

The user scans the QR code with Google Authenticator, Authy, or any standard TOTP app, and saves the backup codes somewhere safe. Verification follows RFC 4226 + RFC 6238: a 6-digit code on a 30-second window, with a ±1 window tolerance to absorb clock drift between the user's device and the server.

WebAuthn / FIDO2 setup (via Bridge):

The user initiates registration and their browser calls the native WebAuthn API (navigator.credentials.create()). Aeion issues a fresh challenge and registration options scoped to your domain, the user touches their security key (YubiKey) or uses Touch ID / Windows Hello, and the resulting credential is registered — only the public key is stored; the private key never leaves the hardware.

MFA verification at login:

After password verification, the user is prompted for their MFA code (TOTP) or hardware-key touch (WebAuthn), and the platform verifies it before issuing a session — a login can't complete without a valid factor.

Navigate: Identity & Security → API Keys → Generate New Key

API key creation:

Create a key with a name, a set of granted permissions, an optional rate limit, an optional IP allowlist, and an optional expiry:

{ "name": "CRM Integration", "scopes": ["crm.contacts.read", "crm.contacts.write", "crm.deals.read", "crm.deals.write"], "rateLimit": 1000, // requests per minute "allowedIps": ["203.0.113.0/24"], // optional CIDR allowlist "expiresAt": "2027-01-01" // optional expiry }

The response — shown only once — includes the full key. Save it immediately: only a secure hash is stored server-side, so it can't be retrieved later.

Using API keys:

bash curl -H "Authorization: Bearer ak_01HQZWXKM2R3P4Q5S6T7V8W9X_YZ3K4M5N6P7Q8R9S0T1U2V3W4X" \ https://api.your-domain.com/crm/contacts

Key verification flow:

typescript // Every request: // 1. Hash incoming key → SHA-256 // 2. Lookup by hash in DB // 3. Check expiry // 4. Check IP against allowedIps // 5. Check scopes // 6. Return 403 if any check fails // Platform-wide Redis rate limiting also applies per route/collection.

Navigate: Identity & Security → Roles & Permissions

Role hierarchy:

superadmin → Full platform access, all tenants, all settings admin → Tenant admin, user management, billing premium → Full feature access (e.g. Salesforce integration) member → Basic access (default for new users) guest → Read-only access

Role elevation on billing subscription:

Role assignment is wired directly to your billing lifecycle. When a user's subscription is created, they're automatically elevated to the plan's associated role (defaulting to "premium" if none is configured). When their subscription is canceled or expires, they're automatically demoted back to a base role. No manual intervention required, and no risk of a lapsed subscription retaining premium access.

Manual role assignment:

Admins can also elevate or demote any user directly from the Roles & Permissions console — useful for one-off exceptions, support cases, or onboarding a user before their billing record syncs.

Navigate: Identity & Security → Security Settings → Enable Magic Links

Magic link flow:

A user requests a magic link with just their email and an intent (sign-in, invitation, or email verification). The link's token is encrypted before storage and delivered by email; when the user clicks it, the token is verified and a session is created automatically — no password required.

Magic links expire after 15 minutes and are invalidated the moment they're used, so a link can't be replayed even if it's intercepted after the fact.

Navigate: Identity & Security → Login History

Login history records:

```typescript // Every login attempt recorded: // { email, status, ip, userAgent, riskScore, riskFactors[], location{}, deviceFingerprint }

// Suspicious login detection: // riskScore >= 70 → auth.login.suspicious event + security alert email

// Example: First login from a new device in a new country // stacks multiple risk factors and crosses the suspicious threshold // → Suspicious alert sent to user // → Admin notified in security dashboard

// Login history is retained for a flat 90 days by default (included free // with every Aeion module), which satisfies most compliance requirements ```

Security dashboard metrics:

Total logins (30 days) Successful vs failed ratio MFA adoption rate (% of users with MFA enabled) OAuth connections by provider Suspicious login attempts flagged Top countries by login volume Top devices by login volume

Navigate: Identity & Security → SSO Connections → Add SSO Provider

OIDC SSO (recommended — federates Okta, Auth0, Azure AD/Entra ID, Ping Identity, OneLogin, JumpCloud, custom corporate IdPs):

```bash # In your OIDC provider: # Create application with redirect URI: https://your-domain.com/api/auth/oauth/oidc/callback # Scopes: openid, profile, email

OIDC_CLIENT_ID=your-client-id OIDC_CLIENT_SECRET=your-client-secret OIDC_AUTHORIZE_URL=https://your-idp.com/oauth2/v1/authorize OIDC_TOKEN_URL=https://your-idp.com/oauth2/v1/token OIDC_USERINFO_URL=https://your-idp.com/oauth2/v1/userinfo ```

Other built-in OAuth providers (configure via the admin UI): Google, GitHub, Microsoft, Apple, Facebook, Twitter/X, LinkedIn, Discord, Slack. Each uses its provider's OAuth 2.0 endpoints with PKCE.

SAML 2.0 is supported natively. Configure a connection under Enterprise Auth in the admin (or POST /api/v1/saml-admin/connections): paste your IdP's SSO URL + signing certificate, set your SP entity ID, and map the email/name/group attributes. Aeion publishes SP metadata at /api/auth/saml/{connectionId}/metadata to hand to your IdP, and consumes assertions at the ACS endpoint. Signed assertions are required by default; Single Logout and encrypted assertions are supported. SCIM 2.0 directory sync (/api/auth/scim/v2/Users + /Groups + /Bulk) keeps the user list continuously in step with your directory.

SSO login flow:

typescript // User clicks "Sign in with SSO" → redirected to IdP // User authenticates with IdP → redirected back // The OAuth pipeline processes the callback // → Links OAuthConnection to user account (or creates new user) // → Creates session // → Returns JWT