Saleor Security
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io authentication JWT tokens for current JWT authentication flow
- Web-search
site:docs.saleor.io apps permissions for App token authentication and permission model
- Web-search
site:docs.saleor.io OIDC OpenID Connect for OIDC integration configuration
- Web-search
saleor webhook payload signature JWS verification for webhook signature verification
- Fetch
https://docs.saleor.io/docs/developer/app-store/apps/overview for App authentication patterns
- Web-search
saleor CORS security headers production for CORS and header configuration
JWT Authentication Flow
Saleor uses JSON Web Tokens for staff and customer authentication. Tokens are obtained via GraphQL mutations and passed as Bearer tokens.
Token Lifecycle
| Operation |
GraphQL Mutation |
Token Type |
Expiry |
| Customer login |
tokenCreate |
Access + Refresh |
Access: 5 min, Refresh: 30 days |
| Staff login |
tokenCreate |
Access + Refresh |
Access: 5 min, Refresh: 30 days |
| Refresh |
tokenRefresh |
New access token |
5 min (configurable) |
| Verify |
tokenVerify |
Validity check |
N/A |
| Deactivate |
tokensDeactivateAll |
Invalidate all |
N/A |
Token Usage
- Pass the access token in the
Authorization: Bearer <token> header
- Refresh tokens are used only to obtain new access tokens
- Access tokens are short-lived by design to limit exposure
- CSRF token is required for cookie-based authentication (Dashboard)
OIDC Integration
Saleor supports OpenID Connect for federated authentication. Saleor acts as an OAuth client, delegating login to an external identity provider.
OIDC Configuration Modes
| Mode |
Description |
Use Case |
| Saleor as OAuth client |
Delegates login to external IdP |
SSO with corporate directory |
| Authorization Code flow |
Standard OIDC flow with code exchange |
Web applications |
| ID token login |
Accept ID token from external IdP |
Mobile or SPA apps |
Key OIDC Settings
OIDC_JWKS_URL — JSON Web Key Set endpoint of the IdPOIDC_OAUTH_CLIENT_ID — Client ID registered with IdPOIDC_OAUTH_CLIENT_SECRET — Client secret for code exchange- Configured via an OIDC authentication App (not environment variables)
App Token Authentication
Apps authenticate using App tokens (permanent Bearer tokens) rather than JWT:
| Token Type |
Obtained Via |
Expiry |
Scope |
| App token |
appTokenCreate mutation |
Never (manual revoke) |
App's declared permissions |
| Auth token (install handshake) |
Token exchange during install |
Session-scoped |
Full App permissions |
- Apps declare required permissions in their manifest
- The store admin grants permissions during App installation
- App tokens are scoped to exactly the permissions granted
Permission Model
Saleor uses a granular permission system applied to staff users, permission groups, and Apps.
Core Permissions
| Permission |
Grants Access To |
MANAGE_PRODUCTS |
Create, update, delete products, variants, types |
MANAGE_ORDERS |
View and modify orders, fulfillments, returns |
MANAGE_APPS |
Install, configure, and remove Apps |
MANAGE_USERS |
Manage customer accounts |
MANAGE_STAFF |
Manage staff users and permission groups |
MANAGE_CHECKOUTS |
Access and modify checkouts |
MANAGE_CHANNELS |
Create and configure channels |
MANAGE_SHIPPING |
Configure shipping zones and methods |
MANAGE_DISCOUNTS |
Manage promotions, vouchers, gift cards |
MANAGE_TRANSLATIONS |
Manage translations for all entities |
MANAGE_SETTINGS |
Access to site-wide settings |
MANAGE_PAGE_TYPES_AND_ATTRIBUTES |
Manage page types and attribute schemas |
MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES |
Manage product types and attribute schemas |
HANDLE_PAYMENTS |
Process transactions and refunds |
HANDLE_TAXES |
Configure tax providers |
Permission Groups
- Staff users are assigned to permission groups
- Each group has a set of permissions
- A staff user inherits the union of all group permissions
- Superuser (
is_superuser) bypasses all permission checks
Rate Limiting
- Configure via
THROTTLE_CLASSES in Django settings
- Default throttle rates for anonymous, authenticated, and mutation requests
- Per-IP and per-user rate limiting available
- Webhook endpoints should have separate rate limits
- Plugin/App-specific rate limiting via middleware
CORS Configuration
| Setting |
Description |
Example |
ALLOWED_ORIGINS |
Origins permitted to make requests |
["https://storefront.example.com"] |
ALLOWED_HOSTS |
Hostnames the server responds to |
["api.example.com"] |
CORS_ALLOW_CREDENTIALS |
Allow cookies cross-origin |
true for Dashboard |
CORS_ALLOW_HEADERS |
Additional allowed headers |
["authorization-bearer", "content-type"] |
- Use
django-cors-headers middleware (included in Saleor)
- Never use
CORS_ALLOW_ALL_ORIGINS = True in production
- Restrict origins to known storefronts, Dashboard, and Apps
Security Headers
| Header |
Value |
Purpose |
Strict-Transport-Security |
max-age=31536000; includeSubDomains |
Enforce HTTPS |
X-Content-Type-Options |
nosniff |
Prevent MIME-type sniffing |
X-Frame-Options |
DENY or SAMEORIGIN |
Prevent clickjacking |
Content-Security-Policy |
Directive-based |
Restrict resource loading |
Referrer-Policy |
strict-origin-when-cross-origin |
Limit referrer leakage |
Django SECRET_KEY Management
- Generate a strong random key: at least 50 characters
- Store in environment variable
SECRET_KEY, never in source code
- Rotate periodically — existing sessions and tokens are invalidated on rotation
- Use separate keys for each environment (dev, staging, production)
SSL/TLS Enforcement
- Set
SECURE_SSL_REDIRECT = True in Django settings
- Set
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https") behind a reverse proxy
- Use
SESSION_COOKIE_SECURE = True and CSRF_COOKIE_SECURE = True
- All GraphQL API traffic must use HTTPS in production
Webhook Payload Signature Verification
Saleor signs every webhook with the Saleor-Signature header. Since 3.5+, the default is JWS (RS256) using a public key from /.well-known/jwks.json. Legacy HMAC-SHA256 (via App secret) is deprecated and will be removed in 4.0.
- Verify JWS signatures by fetching the public key from
<saleor-domain>/.well-known/jwks.json
- Use the
saleor-app-sdk built-in middleware for automatic verification
- Reject requests with missing or invalid signatures
Security Hardening Checklist
| Item |
Action |
| HTTPS |
Enable SECURE_SSL_REDIRECT, set cookie secure flags |
| SECRET_KEY |
Strong random value, environment variable only |
| ALLOWED_HOSTS |
Restrict to actual domain names |
| CORS |
Restrict to known origins |
| DEBUG |
Set DEBUG = False in production |
| Database |
Use SSL connections, restrict network access |
| App tokens |
Rotate periodically, grant minimal permissions |
| Webhook signatures |
Always verify JWS/HMAC on every webhook handler |
| Rate limiting |
Enable throttling on all public endpoints |
| Dependencies |
Pin versions, audit with pip-audit or safety |
| Admin access |
Use permission groups with least-privilege |
| Logs |
Never log tokens, secrets, or PII |
Best Practices
- Always verify webhook signatures (JWS default, HMAC deprecated) before processing payloads
- Use short-lived JWT access tokens and refresh tokens for session management
- Grant Apps the minimum permissions required for their functionality
- Store all secrets (SECRET_KEY, database password, App secrets) in environment variables
- Enable HTTPS everywhere and set all security-related Django settings
- Use OIDC for single sign-on rather than managing passwords directly
- Implement rate limiting to protect against brute-force and denial-of-service attacks
- Audit permission groups regularly to enforce least-privilege access
- Keep Saleor and all Python dependencies up to date with security patches
- Use
ALLOWED_HOSTS and CORS to prevent host header attacks and cross-origin abuse
Fetch the security documentation for current JWT authentication flow, OIDC configuration, and permission model before implementing.
1---2name: saleor-security3description: Secure Saleor applications — JWT authentication, OIDC integration, App tokens, permission model, rate limiting, CORS, and security headers. Use when configuring Saleor security.4---56# Saleor Security78## Before writing code910**Fetch live docs**:111. Web-search `site:docs.saleor.io authentication JWT tokens` for current JWT authentication flow122. Web-search `site:docs.saleor.io apps permissions` for App token authentication and permission model133. Web-search `site:docs.saleor.io OIDC OpenID Connect` for OIDC integration configuration144. Web-search `saleor webhook payload signature JWS verification` for webhook signature verification155. Fetch `https://docs.saleor.io/docs/developer/app-store/apps/overview` for App authentication patterns166. Web-search `saleor CORS security headers production` for CORS and header configuration1718## JWT Authentication Flow1920Saleor uses JSON Web Tokens for staff and customer authentication. Tokens are obtained via GraphQL mutations and passed as Bearer tokens.2122### Token Lifecycle2324| Operation | GraphQL Mutation | Token Type | Expiry |25|-----------|-----------------|------------|--------|26| **Customer login** | `tokenCreate` | Access + Refresh | Access: 5 min, Refresh: 30 days |27| **Staff login** | `tokenCreate` | Access + Refresh | Access: 5 min, Refresh: 30 days |28| **Refresh** | `tokenRefresh` | New access token | 5 min (configurable) |29| **Verify** | `tokenVerify` | Validity check | N/A |30| **Deactivate** | `tokensDeactivateAll` | Invalidate all | N/A |3132### Token Usage3334- Pass the access token in the `Authorization: Bearer <token>` header35- Refresh tokens are used only to obtain new access tokens36- Access tokens are short-lived by design to limit exposure37- CSRF token is required for cookie-based authentication (Dashboard)3839## OIDC Integration4041Saleor supports OpenID Connect for federated authentication. Saleor acts as an OAuth client, delegating login to an external identity provider.4243### OIDC Configuration Modes4445| Mode | Description | Use Case |46|------|-------------|----------|47| **Saleor as OAuth client** | Delegates login to external IdP | SSO with corporate directory |48| **Authorization Code flow** | Standard OIDC flow with code exchange | Web applications |49| **ID token login** | Accept ID token from external IdP | Mobile or SPA apps |5051### Key OIDC Settings5253- `OIDC_JWKS_URL` — JSON Web Key Set endpoint of the IdP54- `OIDC_OAUTH_CLIENT_ID` — Client ID registered with IdP55- `OIDC_OAUTH_CLIENT_SECRET` — Client secret for code exchange56- Configured via an OIDC authentication App (not environment variables)5758## App Token Authentication5960Apps authenticate using App tokens (permanent Bearer tokens) rather than JWT:6162| Token Type | Obtained Via | Expiry | Scope |63|-----------|-------------|--------|-------|64| **App token** | `appTokenCreate` mutation | Never (manual revoke) | App's declared permissions |65| **Auth token** (install handshake) | Token exchange during install | Session-scoped | Full App permissions |6667- Apps declare required permissions in their manifest68- The store admin grants permissions during App installation69- App tokens are scoped to exactly the permissions granted7071## Permission Model7273Saleor uses a granular permission system applied to staff users, permission groups, and Apps.7475### Core Permissions7677| Permission | Grants Access To |78|-----------|-----------------|79| `MANAGE_PRODUCTS` | Create, update, delete products, variants, types |80| `MANAGE_ORDERS` | View and modify orders, fulfillments, returns |81| `MANAGE_APPS` | Install, configure, and remove Apps |82| `MANAGE_USERS` | Manage customer accounts |83| `MANAGE_STAFF` | Manage staff users and permission groups |84| `MANAGE_CHECKOUTS` | Access and modify checkouts |85| `MANAGE_CHANNELS` | Create and configure channels |86| `MANAGE_SHIPPING` | Configure shipping zones and methods |87| `MANAGE_DISCOUNTS` | Manage promotions, vouchers, gift cards |88| `MANAGE_TRANSLATIONS` | Manage translations for all entities |89| `MANAGE_SETTINGS` | Access to site-wide settings |90| `MANAGE_PAGE_TYPES_AND_ATTRIBUTES` | Manage page types and attribute schemas |91| `MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES` | Manage product types and attribute schemas |92| `HANDLE_PAYMENTS` | Process transactions and refunds |93| `HANDLE_TAXES` | Configure tax providers |9495### Permission Groups9697- Staff users are assigned to permission groups98- Each group has a set of permissions99- A staff user inherits the union of all group permissions100- Superuser (`is_superuser`) bypasses all permission checks101102## Rate Limiting103104- Configure via `THROTTLE_CLASSES` in Django settings105- Default throttle rates for anonymous, authenticated, and mutation requests106- Per-IP and per-user rate limiting available107- Webhook endpoints should have separate rate limits108- Plugin/App-specific rate limiting via middleware109110## CORS Configuration111112| Setting | Description | Example |113|---------|-------------|---------|114| `ALLOWED_ORIGINS` | Origins permitted to make requests | `["https://storefront.example.com"]` |115| `ALLOWED_HOSTS` | Hostnames the server responds to | `["api.example.com"]` |116| `CORS_ALLOW_CREDENTIALS` | Allow cookies cross-origin | `true` for Dashboard |117| `CORS_ALLOW_HEADERS` | Additional allowed headers | `["authorization-bearer", "content-type"]` |118119- Use `django-cors-headers` middleware (included in Saleor)120- Never use `CORS_ALLOW_ALL_ORIGINS = True` in production121- Restrict origins to known storefronts, Dashboard, and Apps122123## Security Headers124125| Header | Value | Purpose |126|--------|-------|---------|127| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Enforce HTTPS |128| `X-Content-Type-Options` | `nosniff` | Prevent MIME-type sniffing |129| `X-Frame-Options` | `DENY` or `SAMEORIGIN` | Prevent clickjacking |130| `Content-Security-Policy` | Directive-based | Restrict resource loading |131| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limit referrer leakage |132133## Django SECRET_KEY Management134135- Generate a strong random key: at least 50 characters136- Store in environment variable `SECRET_KEY`, never in source code137- Rotate periodically — existing sessions and tokens are invalidated on rotation138- Use separate keys for each environment (dev, staging, production)139140## SSL/TLS Enforcement141142- Set `SECURE_SSL_REDIRECT = True` in Django settings143- Set `SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")` behind a reverse proxy144- Use `SESSION_COOKIE_SECURE = True` and `CSRF_COOKIE_SECURE = True`145- All GraphQL API traffic must use HTTPS in production146147## Webhook Payload Signature Verification148149Saleor signs every webhook with the `Saleor-Signature` header. Since 3.5+, the default is **JWS (RS256)** using a public key from `/.well-known/jwks.json`. Legacy HMAC-SHA256 (via App secret) is deprecated and will be removed in 4.0.150- Verify JWS signatures by fetching the public key from `<saleor-domain>/.well-known/jwks.json`151- Use the `saleor-app-sdk` built-in middleware for automatic verification152- Reject requests with missing or invalid signatures153154## Security Hardening Checklist155156| Item | Action |157|------|--------|158| HTTPS | Enable `SECURE_SSL_REDIRECT`, set cookie secure flags |159| SECRET_KEY | Strong random value, environment variable only |160| ALLOWED_HOSTS | Restrict to actual domain names |161| CORS | Restrict to known origins |162| DEBUG | Set `DEBUG = False` in production |163| Database | Use SSL connections, restrict network access |164| App tokens | Rotate periodically, grant minimal permissions |165| Webhook signatures | Always verify JWS/HMAC on every webhook handler |166| Rate limiting | Enable throttling on all public endpoints |167| Dependencies | Pin versions, audit with `pip-audit` or `safety` |168| Admin access | Use permission groups with least-privilege |169| Logs | Never log tokens, secrets, or PII |170171## Best Practices172173- Always verify webhook signatures (JWS default, HMAC deprecated) before processing payloads174- Use short-lived JWT access tokens and refresh tokens for session management175- Grant Apps the minimum permissions required for their functionality176- Store all secrets (SECRET_KEY, database password, App secrets) in environment variables177- Enable HTTPS everywhere and set all security-related Django settings178- Use OIDC for single sign-on rather than managing passwords directly179- Implement rate limiting to protect against brute-force and denial-of-service attacks180- Audit permission groups regularly to enforce least-privilege access181- Keep Saleor and all Python dependencies up to date with security patches182- Use `ALLOWED_HOSTS` and CORS to prevent host header attacks and cross-origin abuse183184Fetch the security documentation for current JWT authentication flow, OIDC configuration, and permission model before implementing.
OrcaQubits