saleor-security
Secure Saleor applications — JWT authentication, OIDC integration, App tokens, permission model, rate limiting, CORS, and security headers. Use when configuring Saleor security.
Best use case
saleor-security is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Secure Saleor applications — JWT authentication, OIDC integration, App tokens, permission model, rate limiting, CORS, and security headers. Use when configuring Saleor security.
Teams using saleor-security should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/saleor-security/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How saleor-security Compares
| Feature / Agent | saleor-security | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Secure Saleor applications — JWT authentication, OIDC integration, App tokens, permission model, rate limiting, CORS, and security headers. Use when configuring Saleor security.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Saleor Security
## Before writing code
**Fetch live docs**:
1. Web-search `site:docs.saleor.io authentication JWT tokens` for current JWT authentication flow
2. Web-search `site:docs.saleor.io apps permissions` for App token authentication and permission model
3. Web-search `site:docs.saleor.io OIDC OpenID Connect` for OIDC integration configuration
4. Web-search `saleor webhook payload signature JWS verification` for webhook signature verification
5. Fetch `https://docs.saleor.io/docs/developer/app-store/apps/overview` for App authentication patterns
6. 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.Related Skills
woo-security
Implement WooCommerce security — nonces, capabilities, input sanitization, output escaping, data validation, PCI compliance considerations, and WordPress security best practices. Use when hardening a WooCommerce store or reviewing security posture.
webmcp-security
Implement WebMCP security best practices — permission model, data minimization, honest descriptions, input validation, fingerprinting prevention, and fraud mitigation. Use when auditing or hardening WebMCP tool implementations.
spree-security
Secure a Spree deployment — Rails credentials and env-var hygiene, Devise auth (Spree v5 ships it in-core; `spree_auth_devise` is archived), CanCanCan authorization rules, Doorkeeper OAuth2 scopes, Storefront publishable key vs admin API key, webhook HMAC verification, OWASP Top 10 for Rails (mass assignment, CSRF, SQL injection via Ransack, XSS, IDOR through prefixed IDs), PCI scope (Spree never touches raw cards thanks to gateway tokenization), and multi-store data isolation. Use when auditing a Spree app, hardening a deploy, or addressing a security incident.
shopify-security
Secure Shopify applications — HMAC webhook verification, session token validation, OAuth scope management, Content Security Policy, GDPR mandatory webhooks, input validation, and secure coding practices. Use when implementing Shopify security features.
sf-security
Implement Salesforce Commerce security — SLAS OAuth 2.1, session management, CSRF tokens, XSS prevention (isprint encoding in ISML), PCI compliance, RBAC in Business Manager, OWASP Top 10 protections, and Salesforce Shield for B2B. Use when implementing authentication or security controls.
saleor-webhooks
Configure Saleor webhooks — async and sync events, subscription payloads, JWS/HMAC signature verification, retry policy, and event types. Use when building webhook-driven integrations.
saleor-testing
Test Saleor applications — pytest setup, Django test client, GraphQL test patterns, App testing, factory_boy fixtures, and webhook testing. Use when writing tests for Saleor projects.
saleor-storefront
Build Next.js storefronts for Saleor — GraphQL client setup, channel routing, Tailwind CSS, server components, checkout flow, and SEO. Use when developing Saleor storefronts.
saleor-shipping
Configure Saleor shipping — shipping zones, methods (price/weight-based), custom shipping Apps, warehouse-based allocation, and click-and-collect. Use when setting up delivery options.
saleor-setup
Set up a Saleor development environment — saleor-platform Docker Compose, CLI, PostgreSQL/Redis prerequisites, manage.py commands, environment variables, project structure. Use when starting a new Saleor project.
saleor-promotions
Configure Saleor promotions — catalog promotions, order promotions, vouchers, manual discounts, gift cards, and discount stacking. Use when setting up pricing rules.
saleor-payments
Implement Saleor payment processing — transaction-based payment flow, payment Apps, sync webhook events, Stripe/Adyen patterns, and refunds. Use when building payment integrations.