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 IdP
OIDC_OAUTH_CLIENT_ID — Client ID registered with IdP
OIDC_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.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-security7---89# Saleor Security1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io authentication JWT tokens` for current JWT authentication flow152. Web-search `site:docs.saleor.io apps permissions` for App token authentication and permission model163. Web-search `site:docs.saleor.io OIDC OpenID Connect` for OIDC integration configuration174. Web-search `saleor webhook payload signature JWS verification` for webhook signature verification185. Fetch `https://docs.saleor.io/docs/developer/app-store/apps/overview` for App authentication patterns196. Web-search `saleor CORS security headers production` for CORS and header configuration2021## JWT Authentication Flow2223Saleor uses JSON Web Tokens for staff and customer authentication. Tokens are obtained via GraphQL mutations and passed as Bearer tokens.2425### Token Lifecycle2627| Operation | GraphQL Mutation | Token Type | Expiry |28|-----------|-----------------|------------|--------|29| **Customer login** | `tokenCreate` | Access + Refresh | Access: 5 min, Refresh: 30 days |30| **Staff login** | `tokenCreate` | Access + Refresh | Access: 5 min, Refresh: 30 days |31| **Refresh** | `tokenRefresh` | New access token | 5 min (configurable) |32| **Verify** | `tokenVerify` | Validity check | N/A |33| **Deactivate** | `tokensDeactivateAll` | Invalidate all | N/A |3435### Token Usage3637- Pass the access token in the `Authorization: Bearer <token>` header38- Refresh tokens are used only to obtain new access tokens39- Access tokens are short-lived by design to limit exposure40- CSRF token is required for cookie-based authentication (Dashboard)4142## OIDC Integration4344Saleor supports OpenID Connect for federated authentication. Saleor acts as an OAuth client, delegating login to an external identity provider.4546### OIDC Configuration Modes4748| Mode | Description | Use Case |49|------|-------------|----------|50| **Saleor as OAuth client** | Delegates login to external IdP | SSO with corporate directory |51| **Authorization Code flow** | Standard OIDC flow with code exchange | Web applications |52| **ID token login** | Accept ID token from external IdP | Mobile or SPA apps |5354### Key OIDC Settings5556- `OIDC_JWKS_URL` — JSON Web Key Set endpoint of the IdP57- `OIDC_OAUTH_CLIENT_ID` — Client ID registered with IdP58- `OIDC_OAUTH_CLIENT_SECRET` — Client secret for code exchange59- Configured via an OIDC authentication App (not environment variables)6061## App Token Authentication6263Apps authenticate using App tokens (permanent Bearer tokens) rather than JWT:6465| Token Type | Obtained Via | Expiry | Scope |66|-----------|-------------|--------|-------|67| **App token** | `appTokenCreate` mutation | Never (manual revoke) | App's declared permissions |68| **Auth token** (install handshake) | Token exchange during install | Session-scoped | Full App permissions |6970- Apps declare required permissions in their manifest71- The store admin grants permissions during App installation72- App tokens are scoped to exactly the permissions granted7374## Permission Model7576Saleor uses a granular permission system applied to staff users, permission groups, and Apps.7778### Core Permissions7980| Permission | Grants Access To |81|-----------|-----------------|82| `MANAGE_PRODUCTS` | Create, update, delete products, variants, types |83| `MANAGE_ORDERS` | View and modify orders, fulfillments, returns |84| `MANAGE_APPS` | Install, configure, and remove Apps |85| `MANAGE_USERS` | Manage customer accounts |86| `MANAGE_STAFF` | Manage staff users and permission groups |87| `MANAGE_CHECKOUTS` | Access and modify checkouts |88| `MANAGE_CHANNELS` | Create and configure channels |89| `MANAGE_SHIPPING` | Configure shipping zones and methods |90| `MANAGE_DISCOUNTS` | Manage promotions, vouchers, gift cards |91| `MANAGE_TRANSLATIONS` | Manage translations for all entities |92| `MANAGE_SETTINGS` | Access to site-wide settings |93| `MANAGE_PAGE_TYPES_AND_ATTRIBUTES` | Manage page types and attribute schemas |94| `MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES` | Manage product types and attribute schemas |95| `HANDLE_PAYMENTS` | Process transactions and refunds |96| `HANDLE_TAXES` | Configure tax providers |9798### Permission Groups99100- Staff users are assigned to permission groups101- Each group has a set of permissions102- A staff user inherits the union of all group permissions103- Superuser (`is_superuser`) bypasses all permission checks104105## Rate Limiting106107- Configure via `THROTTLE_CLASSES` in Django settings108- Default throttle rates for anonymous, authenticated, and mutation requests109- Per-IP and per-user rate limiting available110- Webhook endpoints should have separate rate limits111- Plugin/App-specific rate limiting via middleware112113## CORS Configuration114115| Setting | Description | Example |116|---------|-------------|---------|117| `ALLOWED_ORIGINS` | Origins permitted to make requests | `["https://storefront.example.com"]` |118| `ALLOWED_HOSTS` | Hostnames the server responds to | `["api.example.com"]` |119| `CORS_ALLOW_CREDENTIALS` | Allow cookies cross-origin | `true` for Dashboard |120| `CORS_ALLOW_HEADERS` | Additional allowed headers | `["authorization-bearer", "content-type"]` |121122- Use `django-cors-headers` middleware (included in Saleor)123- Never use `CORS_ALLOW_ALL_ORIGINS = True` in production124- Restrict origins to known storefronts, Dashboard, and Apps125126## Security Headers127128| Header | Value | Purpose |129|--------|-------|---------|130| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Enforce HTTPS |131| `X-Content-Type-Options` | `nosniff` | Prevent MIME-type sniffing |132| `X-Frame-Options` | `DENY` or `SAMEORIGIN` | Prevent clickjacking |133| `Content-Security-Policy` | Directive-based | Restrict resource loading |134| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limit referrer leakage |135136## Django SECRET_KEY Management137138- Generate a strong random key: at least 50 characters139- Store in environment variable `SECRET_KEY`, never in source code140- Rotate periodically — existing sessions and tokens are invalidated on rotation141- Use separate keys for each environment (dev, staging, production)142143## SSL/TLS Enforcement144145- Set `SECURE_SSL_REDIRECT = True` in Django settings146- Set `SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")` behind a reverse proxy147- Use `SESSION_COOKIE_SECURE = True` and `CSRF_COOKIE_SECURE = True`148- All GraphQL API traffic must use HTTPS in production149150## Webhook Payload Signature Verification151152Saleor 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.153- Verify JWS signatures by fetching the public key from `<saleor-domain>/.well-known/jwks.json`154- Use the `saleor-app-sdk` built-in middleware for automatic verification155- Reject requests with missing or invalid signatures156157## Security Hardening Checklist158159| Item | Action |160|------|--------|161| HTTPS | Enable `SECURE_SSL_REDIRECT`, set cookie secure flags |162| SECRET_KEY | Strong random value, environment variable only |163| ALLOWED_HOSTS | Restrict to actual domain names |164| CORS | Restrict to known origins |165| DEBUG | Set `DEBUG = False` in production |166| Database | Use SSL connections, restrict network access |167| App tokens | Rotate periodically, grant minimal permissions |168| Webhook signatures | Always verify JWS/HMAC on every webhook handler |169| Rate limiting | Enable throttling on all public endpoints |170| Dependencies | Pin versions, audit with `pip-audit` or `safety` |171| Admin access | Use permission groups with least-privilege |172| Logs | Never log tokens, secrets, or PII |173174## Best Practices175176- Always verify webhook signatures (JWS default, HMAC deprecated) before processing payloads177- Use short-lived JWT access tokens and refresh tokens for session management178- Grant Apps the minimum permissions required for their functionality179- Store all secrets (SECRET_KEY, database password, App secrets) in environment variables180- Enable HTTPS everywhere and set all security-related Django settings181- Use OIDC for single sign-on rather than managing passwords directly182- Implement rate limiting to protect against brute-force and denial-of-service attacks183- Audit permission groups regularly to enforce least-privilege access184- Keep Saleor and all Python dependencies up to date with security patches185- Use `ALLOWED_HOSTS` and CORS to prevent host header attacks and cross-origin abuse186187Fetch the security documentation for current JWT authentication flow, OIDC configuration, and permission model before implementing.