- Implemented a new customer portal for users to manage their support requests. - Added functionality for users to create and view their support cases. - Updated article publishing logic to clarify the distinction between approval and visibility in the ticket reply panel. - Enhanced the comment model to include the author's name when comments are made through the customer portal. - Improved UI/UX for the solutions and cases pages, ensuring better clarity on article status and visibility. - Updated documentation to reflect changes in the API and customer portal features.
264 lines
16 KiB
Markdown
264 lines
16 KiB
Markdown
# Authentication
|
|
|
|
BottleCRM has three separate credential types, a short-lived JWT for interactive clients, a
|
|
personal access token for agents and scripts, and a per-org API key for server-to-server
|
|
integrations, and this page describes how each one proves identity and how the server decides
|
|
what it's allowed to do. The rule underneath all three is the same one stated in
|
|
[Multi-tenancy and RLS](multi-tenancy-and-rls.md): identity, org, and role are facts the server
|
|
derives and verifies, never values a client supplies. Nothing in a request body, query string, or
|
|
custom header changes who you are authenticated as.
|
|
|
|
## Token model
|
|
|
|
Interactive sign-in (Google OAuth and passwordless magic-link/OTP) issues a JSON Web Token pair
|
|
built on `djangorestframework-simplejwt`. `SIMPLE_JWT` in `backend/crm/settings.py` sets:
|
|
|
|
```python
|
|
SIMPLE_JWT = {
|
|
"ACCESS_TOKEN_LIFETIME": timedelta(hours=1),
|
|
"REFRESH_TOKEN_LIFETIME": timedelta(days=14),
|
|
"ROTATE_REFRESH_TOKENS": True,
|
|
"BLACKLIST_AFTER_ROTATION": True,
|
|
"ALGORITHM": "HS256",
|
|
"SIGNING_KEY": SECRET_KEY,
|
|
...
|
|
}
|
|
```
|
|
|
|
Access tokens live one hour; refresh tokens live 14 days. Both are signed with `SECRET_KEY` itself.
|
|
There is no separate JWT signing key setting anywhere in this codebase, so rotating `SECRET_KEY`
|
|
invalidates every outstanding token immediately. See
|
|
[Security hardening](../self-hosting/security-hardening.md#secrets) for the operational
|
|
consequences of that. `rest_framework_simplejwt.token_blacklist` is in `INSTALLED_APPS`
|
|
specifically so that `RefreshToken.blacklist()` exists to call: without that app installed,
|
|
`BLACKLIST_AFTER_ROTATION` would be a silent no-op, which is exactly the kind of failure mode this
|
|
codebase's own comment on the `INSTALLED_APPS` entry calls out.
|
|
|
|
Tokens are minted by `OrgAwareRefreshToken` (`backend/common/serializer.py`), a `RefreshToken`
|
|
subclass whose `for_user_and_org(user, org, profile=None)` classmethod embeds org and role claims
|
|
directly in the token payload (see [Claims](#claims)) so the frontend doesn't need a follow-up
|
|
`/api/auth/profile/` call just to learn which org or role it's operating as.
|
|
|
|
Two other credential types exist alongside the JWT, covered later on this page:
|
|
[personal access tokens](#personal-access-tokens) (`bcrm_pat_…`, self-service, scoped to one
|
|
profile) and [organization API keys](#organization-api-keys) (one per org, admin-managed,
|
|
equivalent to an admin session). See
|
|
[Security hardening](../self-hosting/security-hardening.md#token-surfaces) for how their blast
|
|
radii compare.
|
|
|
|
## Claims
|
|
|
|
`OrgAwareRefreshToken.for_user_and_org` embeds, beyond simplejwt's own default claims
|
|
(`token_type`, `exp`, `iat`, `jti`, and the user id under `USER_ID_CLAIM = "user_id"`):
|
|
|
|
- `user_email`, `user_name` (derived from the email, since `User` has no first/last name fields),
|
|
`user_profile_pic`
|
|
- `org_id`, `org_name`, only when an org is present; a token minted before the caller has picked
|
|
an org (see [Organization switching](#organization-switching)) carries neither
|
|
- `org_settings`: `default_currency`, `currency_symbol`, `default_country`
|
|
- `role`, only when a `Profile` was supplied, i.e. only once an org is known
|
|
|
|
`org_id` is the claim that matters most: it's what `GetProfileAndOrg`
|
|
(`backend/common/middleware/get_company.py`) reads to resolve `request.org`, and by extension it's
|
|
what `RequireOrgContext` uses to set the PostgreSQL session variable every RLS policy checks. See
|
|
[Overview](overview.md#request-lifecycle). Critically, the middleware does not simply trust the
|
|
claim: it re-validates it against an active `Profile` row on every single request:
|
|
|
|
```python
|
|
profile = Profile.objects.select_related("org").get(
|
|
user_id=user_id, org_id=org_id, is_active=True
|
|
)
|
|
```
|
|
|
|
So a token minted while a user was a member of an org keeps working only as long as that
|
|
membership stays active. If the membership is revoked after the token was issued, this lookup
|
|
raises `Profile.DoesNotExist` and the middleware turns that into a 403 asking the user to log in
|
|
again, rather than trusting a claim that's gone stale. `role` in the token is a display
|
|
convenience, not the source of truth for authorization, every permission check in
|
|
[Permissions and roles](permissions-and-roles.md) reads `request.profile.role` fresh from the
|
|
database-backed `Profile` the middleware just re-validated, not from the JWT payload.
|
|
|
|
## Refresh and rotation
|
|
|
|
The old documentation for this project asserted refresh-token rotation and server-side tracking
|
|
without pointing at code. Here is what the code actually does. `POST /api/auth/refresh-token/`
|
|
(`OrgAwareTokenRefreshView`, `backend/common/views/auth_views.py`, wired at
|
|
`backend/common/urls.py:58-62`) is the only refresh endpoint. There's no separate route using
|
|
simplejwt's stock `TokenRefreshView`, so the `ROTATE_REFRESH_TOKENS`/`BLACKLIST_AFTER_ROTATION`
|
|
settings shown above describe the intent, but the actual rotation logic is hand-written in this
|
|
view rather than delegated to simplejwt's default serializer:
|
|
|
|
```python
|
|
with transaction.atomic():
|
|
token.blacklist()
|
|
new_token = OrgAwareRefreshToken.for_user_and_org(user, org, profile)
|
|
```
|
|
|
|
The presented refresh token is decoded and validated, its `org_id` claim (if any) is re-checked
|
|
against an active `Profile` exactly as in [Claims](#claims) above. A revoked membership gets a 403
|
|
here too, not a fresh token, and then, in one atomic transaction, the presented token is
|
|
blacklisted and a replacement is minted carrying the same org context. Both writes share a
|
|
transaction specifically so a failure can never leave the caller tokenless while the old token
|
|
remains usable. This is real rotation with real server-side state: `RefreshToken.blacklist()`
|
|
writes to simplejwt's own `OutstandingToken`/`BlacklistedToken` tables (from the
|
|
`token_blacklist` app), which is what a stolen refresh token being replayed after the legitimate
|
|
client has already refreshed would hit. The blacklisted token fails validation on reuse. Those
|
|
bookkeeping rows aren't kept forever; `flush_expired_refresh_tokens`
|
|
(`backend/common/tasks.py`) deletes `OutstandingToken` rows once their own `expires_at` has passed,
|
|
scheduled nightly. See [Background jobs](background-jobs.md).
|
|
|
|
An expired or already-blacklisted refresh token fails with `TokenError`, which this view turns into
|
|
a 401. A refresh token for a `User` whose account has since been deactivated (`user.is_active`)
|
|
also fails, explicitly, with a 403.
|
|
|
|
## Organization switching
|
|
|
|
A signed-in user can belong to more than one org, and a single JWT only ever carries one `org_id`.
|
|
`POST /api/auth/switch-org/` (`OrgSwitchView`) is how a client moves to a different one: it
|
|
requires only `IsAuthenticated` (not `HasOrgContext`), because it has to work for a token that has
|
|
no org claim at all yet, the state a fresh Google OAuth login is in, since
|
|
`GoogleOAuthCallbackView`/`GoogleIdTokenView` both mint their initial token with `org=None` and
|
|
leave org selection to a separate step.
|
|
|
|
The view re-validates membership the same way the refresh endpoint does;
|
|
`Profile.objects.get(user=request.user, org_id=org_id, is_active=True)`, and 403s
|
|
(with an audit-logged `permission_denied` entry) if the caller has no active profile in the
|
|
requested org. It then optionally retires the refresh token the client is switching away from:
|
|
|
|
```python
|
|
if str(token.get("user_id")) != str(request.user.id):
|
|
return
|
|
token.blacklist()
|
|
```
|
|
|
|
That ownership check is not incidental. Without it, `refresh` would let any authenticated caller
|
|
blacklist *any* refresh token they could observe, turning a convenience parameter into a remote
|
|
logout for someone else's session. Retiring the old token is optional by design (existing clients
|
|
don't all send it, and failing the switch over a missing optional field would be worse than letting
|
|
one token expire on its own 14-day schedule), but when it is sent and does belong to the caller, it
|
|
stops working immediately rather than staying valid against the previous org for the rest of its
|
|
life. The org switch itself, retiring the old token and minting the replacement, happens inside
|
|
one transaction for the same reason the refresh endpoint's does.
|
|
|
|
## Personal access tokens
|
|
|
|
Personal access tokens (`bcrm_pat_…`, `PersonalAccessToken` in `backend/common/models.py`) are
|
|
for agents and scripts that need to authenticate as a
|
|
specific user without going through the JWT/OAuth flow on every call. A token is generated once
|
|
(`PersonalAccessToken.generate(profile, name, ...)`), shown to the caller exactly once, and stored
|
|
only as a SHA-256 hash (`token_hash`); the plaintext is not recoverable from the database
|
|
afterward.
|
|
|
|
Resolution happens twice per request, deliberately: `GetProfileAndOrg` resolves the PAT first (so
|
|
`request.org` (and, downstream, the RLS context) is set before `RequireOrgContext` runs), and
|
|
DRF's `PATAuthentication` class (`backend/common/pat_auth.py`) reuses that same resolved token
|
|
(stashed as `request._pat`) rather than looking it up a second time. Both share one validation
|
|
function, `resolve_valid_pat`, which checks the token isn't revoked or expired
|
|
(`PersonalAccessToken.is_valid()`) and that both the owning profile and its org are still active,
|
|
so deactivating a profile cuts off its personal access tokens immediately, with no separate
|
|
revocation step.
|
|
|
|
A token authenticates **as** its owning profile and inherits that profile's role and org in full.
|
|
`PersonalAccessToken` has a `scopes` field, but read the model's own comment before assuming it
|
|
restricts anything:
|
|
|
|
```python
|
|
# NOTE: scopes are stored for forward-compatibility but are NOT enforced in
|
|
# Phase 1: a token always inherits the owning profile's full role/permissions.
|
|
# Do not treat `scopes` as a trust boundary until enforcement lands.
|
|
```
|
|
|
|
Treat a personal access token as exactly as powerful as the user who created it. An admin's PAT
|
|
can do everything that admin can do through the UI. Self-service management lives at
|
|
`profile/tokens/` (a user manages only their own); admin oversight of every token in the org,
|
|
including a deactivated colleague's, is a deliberately separate, admin-only endpoint at
|
|
`org/tokens/`, so the self-service guard is never the thing that has to be loosened to support
|
|
oversight. See [Security hardening](../self-hosting/security-hardening.md#token-surfaces) for that
|
|
distinction in more depth.
|
|
|
|
## Organization API keys
|
|
|
|
Each `Org` has exactly one API key (`Org.api_key`, generated at creation), managed through
|
|
`GET`/`POST /api/org/api-key/` (`OrgApiKeyView`), admin-only in both directions. Unlike a personal
|
|
access token, this key doesn't authenticate as any particular person: `GetProfileAndOrg`'s
|
|
`_process_api_key_auth` resolves a request bearing this key (in a `Token` header) to the org's
|
|
**first active `ADMIN` profile**:
|
|
|
|
```python
|
|
profile = Profile.objects.filter(
|
|
org=organization, role="ADMIN", is_active=True
|
|
).first()
|
|
```
|
|
|
|
Borrowing a real person's profile is what made this key so dangerous: it never expires, there is one
|
|
per tenant so it cannot be revoked per integration, and until scope enforcement landed it could do
|
|
anything that admin could, including delete records and mint a personal access token owned by them.
|
|
|
|
Two limits now apply, both in middleware, before any view runs:
|
|
|
|
- **It is read-only.** Any unsafe method (`POST`, `PUT`, `PATCH`, `DELETE`) is refused with 403. It
|
|
is evaluated as the scope list `("*:read",)`, so the org key and a read-only personal access token
|
|
go through one implementation (`common/scopes.py`).
|
|
- **It cannot reach a credential.** `/api/profile/tokens/`, `/api/org/tokens/` and
|
|
`/api/org/api-key/` are on a deny-list that no scope satisfies, so the key cannot read itself,
|
|
rotate itself, or create a token owned by the admin whose identity it borrowed.
|
|
|
|
`common.external_auth.APIKeyAuthentication` carries the same two gates. It is an independent second
|
|
copy of the key resolution, reached when DRF authenticates a request the middleware skipped, so
|
|
guarding one and not the other would leave the DRF layer admitting what the middleware refuses.
|
|
|
|
`DJANGO_ORG_API_KEY_AUTH=false` turns the whole path off, on every endpoint. It is left on by
|
|
default so an upgrade breaks nothing; a deployment whose integrations have all moved to personal
|
|
access tokens should set it. Even read-only, this key reads every record in the org, so it remains
|
|
the bluntest of the three credential types on this page. Prefer a scoped personal access token.
|
|
|
|
Rotating it (`POST /api/org/api-key/`) invalidates the previous key immediately, and the response
|
|
says so. It's excluded from every nested API representation (`OrganizationSerializer` never embeds
|
|
it) and only ever served by this one endpoint, which now requires an interactive session.
|
|
|
|
## Customer portal credentials
|
|
|
|
Everything above authenticates somebody on **your** side: a member of the org, or a script acting
|
|
with a member's authority. The customer portal (`/api/portal/`) authenticates somebody on the other
|
|
side of the ticket, and it is a separate realm on purpose. Its principal is a `Contact`, which is a
|
|
record in your CRM rather than an account in your system: no `User` row, no `Profile`, no role, no
|
|
org membership.
|
|
|
|
`mint_portal_token` (`backend/common/portal_auth.py`) issues a 24 hour access token carrying
|
|
`typ: "portal"`, `org_id` and `contact_id`. There is no refresh token, so rotation, refresh
|
|
revocation and privilege-change invalidation are absent from this surface entirely. Those are the
|
|
parts of an auth system that are hardest to get right and worst to get wrong, and a portal visited a
|
|
few times per ticket does not need them.
|
|
|
|
The boundary between the two realms is enforced in three independent places, because a boundary
|
|
that depends on every future author remembering it is not a boundary:
|
|
|
|
1. **`PortalContactAuthentication` is never in `DEFAULT_AUTHENTICATION_CLASSES`.** That setting is
|
|
global, so anything listed there authenticates every view in the project. Portal views name the
|
|
class explicitly instead, which means adding an endpoint that accepts a customer is a deliberate
|
|
act.
|
|
2. **The principal reports `is_authenticated = False`.** If a portal token ever does reach an
|
|
internal view, DRF's own `IsAuthenticated` denies it by construction. It reports
|
|
`is_anonymous = True` for the matching reason, which also makes `BaseModel.save` leave
|
|
`created_by` alone rather than trying to stamp a `Contact` into a `User` foreign key.
|
|
3. **`GetProfileAndOrg` refuses a portal token on any path outside `/api/portal/`,** before any view
|
|
runs, with a 403. A view written later cannot opt out of this by forgetting a permission class.
|
|
|
|
Traffic in the other direction needs no special handling. A portal token is minted without a
|
|
`user_id` claim, so SimpleJWT's `get_user` refuses it on its own, and a personal access token, an
|
|
organization API key and an internal JWT are each refused at the portal. All three directions have
|
|
tests.
|
|
|
|
Sign-in itself is a per-org emailed code, deliberately in its own `PortalLoginToken` table rather
|
|
than as a nullable column on `MagicLinkToken`. Sharing that table would mean one verify endpoint
|
|
accepting the other realm's credential, and that is a customer signing in to your internal
|
|
application. Roughly forty duplicated lines buys a boundary a single mistake cannot cross. See
|
|
[API: Customer portal](../api/customer-portal.md) for the endpoints.
|
|
|
|
## Related configuration
|
|
|
|
One piece of related configuration to be aware of: there is no redirect-URI setting. The
|
|
redirect URI used in the Google OAuth code exchange (`GoogleOAuthCallbackView.post`) comes from the
|
|
client's request body on each call (`request.data.get("redirect_uri")`). A `GOOGLE_REDIRECT_URI`
|
|
setting used to exist in `backend/crm/settings.py`, defined and never read; it was removed. See
|
|
[Google OAuth](../self-hosting/google-oauth.md) for the settings that do matter.
|