# Setup

Version: `2.9.8`

## Installation

```bash
npm install @ollaid/native-sso
```

## Quick start

```tsx
import { NativeSSOPage } from '@ollaid/native-sso';

<NativeSSOPage
  saasApiUrl="https://your-saas.com/api"
  iamApiUrl="https://identityam.ollaid.com/api"
  homeUrl="https://your-saas.com/"
  redirectAfterLogin="https://your-saas.com/app"
  onLoginSuccess={(token, user) => {
    console.log(token, user);
  }}
/>
```

Use `getSsoSessionSnapshot()` to read the session and `logout()` to end it.

## Backend env: base block

Every SaaS should have the same base block:

```env
IAM_APP_KEY=...
IAM_PUBLIC_KEY=...
IAM_SECRET_KEY=...
IAM_WEBHOOK_SECRET=...
IAM_API_URL=https://identityam.ollaid.com/api
IAM_AUTH_URL=https://iam.ollaid.com
IAM_BYPASS=false
IAM_DEBUG=false
```

Important: this block configures the SaaS backend that talks to IAM.
It does not create the `/api/sso/*` routes by itself. Your SaaS backend must
implement `config`, `exchange`, `check-token`, `refresh`, `logout`, and `password-link`.
For IAM decrypt traffic, the active route is `POST /api/sso/auth/decrypt`; the older `POST /api/iam/auth/decrypt` path is no longer used.
When SSO tracing is enabled on the IAM backend, detailed request/response logs are written to `storage/logs/sso-YYYY-MM-DD.log`.

## Variable roles

- `IAM_APP_KEY`: SaaS application identifier
- `IAM_PUBLIC_KEY`: application public key
- `IAM_SECRET_KEY`: main SSO secret
- `IAM_WEBHOOK_SECRET`: webhook verification secret
- `IAM_API_URL`: IAM API URL
- `IAM_AUTH_URL`: IAM auth URL
- `IAM_BYPASS`: enables or disables `needs_access` auto-acceptance
- `IAM_DEBUG`: enables or disables debug logs

## Multi-tenant

If the SaaS has multiple frontends or spaces, add tenant-prefixed variants:

```env
IAM_VENDOR_APP_KEY=...
IAM_VENDOR_PUBLIC_KEY=...
IAM_VENDOR_SECRET_KEY=...
IAM_VENDOR_WEBHOOK_SECRET=...
IAM_VENDOR_API_URL=https://identityam.ollaid.com/api
IAM_VENDOR_AUTH_URL=https://iam.ollaid.com
IAM_VENDOR_BYPASS=false
IAM_VENDOR_DEBUG=false

IAM_CLIENT_APP_KEY=...
IAM_CLIENT_PUBLIC_KEY=...
IAM_CLIENT_SECRET_KEY=...
IAM_CLIENT_WEBHOOK_SECRET=...
IAM_CLIENT_API_URL=https://identityam.ollaid.com/api
IAM_CLIENT_AUTH_URL=https://iam.ollaid.com
IAM_CLIENT_BYPASS=false
IAM_CLIENT_DEBUG=false
```

## Rules

- keep the base block for every SaaS
- add tenant blocks only when needed
- never commit real secrets in docs
- `configPrefix` stays on the SaaS side
- native SSO routes do not receive `X-IAM-Config-Prefix`