Back to Details

mapbox-token-security

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Mapbox Token Security Skill

Mapbox令牌安全技能

This skill provides security expertise for managing Mapbox access tokens safely and effectively.
本技能提供安全专业知识，帮助你安全、高效地管理Mapbox访问令牌。

Token Types and When to Use Them

令牌类型及适用场景

Public Tokens (pk.*)

公开令牌（pk.*）

Characteristics:
  • Can be safely exposed in client-side code
  • Limited to specific public scopes only
  • Can have URL restrictions
  • Cannot access sensitive APIs
When to use:
  • Client-side web applications
  • Mobile apps
  • Public-facing demos
  • Embedded maps on websites
Allowed scopes:
  • styles:tiles
    - Display style tiles (raster)
  • styles:read
    - Read style specifications
  • fonts:read
    - Access Mapbox fonts
  • datasets:read
    - Read dataset data
  • vision:read
    - Vision API access
特性：
  • 可安全暴露在客户端代码中
  • 仅能使用特定的公开权限范围
  • 可设置URL限制
  • 无法访问敏感API
适用场景：
  • 客户端Web应用
  • 移动应用
  • 面向公众的演示
  • 网站中的嵌入式地图
允许的权限范围：
  • styles:tiles
    - 显示样式瓦片（栅格）
  • styles:read
    - 读取样式规范
  • fonts:read
    - 访问Mapbox字体
  • datasets:read
    - 读取数据集数据
  • vision:read
    - 访问Vision API

Secret Tokens (sk.*)

保密令牌（sk.*）

Characteristics:
  • NEVER expose in client-side code
  • Full API access with any scopes
  • Server-side use only
  • Can create/manage other tokens
When to use:
  • Server-side applications
  • Backend services
  • CI/CD pipelines
  • Administrative tasks
  • Token management
Common scopes:
  • styles:write
    - Create/modify styles
  • styles:list
    - List all styles
  • tokens:read
    - View token information
  • tokens:write
    - Create/modify tokens
  • User feedback management scopes
特性：
  • 绝对不能暴露在客户端代码中
  • 拥有所有API的访问权限，可配置任意权限范围
  • 仅适用于服务端场景
  • 可创建/管理其他令牌
适用场景：
  • 服务端应用
  • 后端服务
  • CI/CD流水线
  • 管理任务
  • 令牌管理
常用权限范围：
  • styles:write
    - 创建/修改样式
  • styles:list
    - 列出所有样式
  • tokens:read
    - 查看令牌信息
  • tokens:write
    - 创建/修改令牌
  • 用户反馈管理权限范围

Temporary Tokens (tk.*)

临时令牌（tk.*）

Characteristics:
  • Short-lived (max 1 hour)
  • Created by secret tokens
  • Single-purpose use
  • Automatically expire
When to use:
  • One-time operations
  • Temporary delegated access
  • Short-lived demos
  • Security-conscious workflows
特性：
  • 有效期短（最长1小时）
  • 由保密令牌创建
  • 单一用途
  • 自动过期
适用场景：
  • 一次性操作
  • 临时委托访问
  • 短期演示
  • 高安全要求的工作流

Scope Management Best Practices

权限范围管理最佳实践

Principle of Least Privilege

最小权限原则

Always grant the minimum scopes needed:
❌ Bad:
javascript
// Overly permissive - don't do this
{
  scopes: [
    'styles:read',
    'styles:write',
    'styles:list',
    'styles:delete',
    'tokens:read',
    'tokens:write'
  ];
}
✅ Good:
javascript
// Only what's needed for displaying a map
{
  scopes: ['styles:read', 'fonts:read'];
}
始终只授予所需的最小权限范围：
❌ 错误示例：
javascript
// 权限过于宽泛 - 请勿这样做
{
  scopes: [
    'styles:read',
    'styles:write',
    'styles:list',
    'styles:delete',
    'tokens:read',
    'tokens:write'
  ];
}
✅ 正确示例：
javascript
// 仅授予显示地图所需的权限
{
  scopes: ['styles:read', 'fonts:read'];
}

Scope Combinations by Use Case

按场景组合权限范围

Public Map Display (client-side):
json
{
  "scopes": ["styles:read", "fonts:read", "styles:tiles"],
  "note": "Public token for map display",
  "allowedUrls": ["https://myapp.com/*"]
}
Style Management (server-side):
json
{
  "scopes": ["styles:read", "styles:write", "styles:list"],
  "note": "Backend style management - SECRET TOKEN"
}
Token Administration (server-side):
json
{
  "scopes": ["tokens:read", "tokens:write"],
  "note": "Token management only - SECRET TOKEN"
}
Read-Only Access:
json
{
  "scopes": ["styles:list", "styles:read", "tokens:read"],
  "note": "Auditing/monitoring - SECRET TOKEN"
}
公开地图展示（客户端）：
json
{
  "scopes": ["styles:read", "fonts:read", "styles:tiles"],
  "note": "用于地图展示的公开令牌",
  "allowedUrls": ["https://myapp.com/*"]
}
样式管理（服务端）：
json
{
  "scopes": ["styles:read", "styles:write", "styles:list"],
  "note": "后端样式管理 - 保密令牌"
}
令牌管理（服务端）：
json
{
  "scopes": ["tokens:read", "tokens:write"],
  "note": "仅用于令牌管理 - 保密令牌"
}
只读访问：
json
{
  "scopes": ["styles:list", "styles:read", "tokens:read"],
  "note": "审计/监控 - 保密令牌"
}

URL Restrictions

URL限制

Why URL Restrictions Matter

URL限制的重要性

URL restrictions limit where a public token can be used, preventing unauthorized usage if the token is exposed.
URL限制可限定公开令牌的使用范围，防止令牌暴露后被未授权使用。

Effective URL Patterns

有效的URL模式

✅ Recommended patterns:
https://myapp.com/*           # Production domain
https://*.myapp.com/*         # All subdomains
https://staging.myapp.com/*   # Staging environment
http://localhost:*            # Local development
❌ Avoid these:
*                             # No restriction (insecure)
http://*                      # Any HTTP site (insecure)
*.com/*                       # Too broad
✅ 推荐模式：
https://myapp.com/*           # 生产环境域名
https://*.myapp.com/*         # 所有子域名
https://staging.myapp.com/*   # 预发布环境
http://localhost:*            # 本地开发
❌ 应避免的模式：
*                             # 无限制（不安全）
http://*                      # 任意HTTP站点（不安全）
*.com/*                       # 范围过宽

Multiple Environment Strategy

多环境策略

Create separate tokens for each environment:
javascript
// Production
{
  note: "Production - myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://myapp.com/*", "https://www.myapp.com/*"]
}

// Staging
{
  note: "Staging - staging.myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://staging.myapp.com/*"]
}

// Development
{
  note: "Development - localhost",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["http://localhost:*", "http://127.0.0.1:*"]
}
为每个环境创建独立的令牌：
javascript
// 生产环境
{
  note: "生产环境 - myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://myapp.com/*", "https://www.myapp.com/*"]
}

// 预发布环境
{
  note: "预发布环境 - staging.myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://staging.myapp.com/*"]
}

// 开发环境
{
  note: "开发环境 - localhost",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["http://localhost:*", "http://127.0.0.1:*"]
}

Token Storage and Handling

令牌存储与处理

Server-Side (Secret Tokens)

服务端（保密令牌）

✅ DO:
  • Store in environment variables
  • Use secret management services (AWS Secrets Manager, HashiCorp Vault)
  • Encrypt at rest
  • Limit access via IAM policies
  • Log token usage
❌ DON'T:
  • Hardcode in source code
  • Commit to version control
  • Store in plaintext configuration files
  • Share via email or Slack
  • Reuse across multiple services
Example: Secure Environment Variable:
bash
undefined
✅ 正确做法：
  • 存储在环境变量中
  • 使用密钥管理服务（AWS Secrets Manager、HashiCorp Vault）
  • 静态存储时加密
  • 通过IAM策略限制访问
  • 记录令牌使用情况
❌ 错误做法：
  • 硬编码到源代码中
  • 提交到版本控制系统
  • 存储在明文配置文件中
  • 通过邮件或Slack分享
  • 在多个服务间复用
示例：安全的环境变量配置
bash
undefined

.env (NEVER commit this file)

.env文件（绝对不要提交到版本库）

MAPBOX_SECRET_TOKEN=sk.ey...
MAPBOX_SECRET_TOKEN=sk.ey...

.gitignore (ALWAYS include .env)

.gitignore文件（必须包含.env）

.env .env.local .env.*.local
undefined
.env .env.local .env.*.local
undefined

Client-Side (Public Tokens)

客户端（公开令牌）

✅ DO:
  • Use public tokens only
  • Apply URL restrictions
  • Use different tokens per app
  • Rotate periodically
  • Monitor usage
❌ DON'T:
  • Expose secret tokens
  • Use tokens without URL restrictions
  • Share tokens between unrelated apps
  • Use tokens with excessive scopes
Example: Safe Client Usage:
javascript
// Public token with URL restrictions - SAFE
const mapboxToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';

// This token is restricted to your domain
// and only has styles:read scope
mapboxgl.accessToken = mapboxToken;
✅ 正确做法：
  • 仅使用公开令牌
  • 配置URL限制
  • 为每个应用使用不同的令牌
  • 定期轮换
  • 监控使用情况
❌ 错误做法：
  • 暴露保密令牌
  • 使用未配置URL限制的令牌
  • 在不相关的应用间共享令牌
  • 使用权限范围过大的令牌
示例：安全的客户端使用方式
javascript
undefined

Token Rotation Strategy

带URL限制的公开令牌 - 安全

When to Rotate Tokens

—
Mandatory rotation:
  • Token exposed in public repository
  • Team member leaves with token access
  • Suspected compromise or breach
  • Service decommissioning
  • Compliance requirements
Scheduled rotation:
  • Every 90 days (recommended for production)
  • Every 30 days (high-security environments)
  • After major deployments
  • During security audits
const mapboxToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';

Rotation Process

该令牌仅可在你的域名下使用

—

且仅拥有styles:read权限

Zero-downtime rotation:
  1. Create new token with same scopes
  2. Deploy new token to canary/staging environment
  3. Verify functionality with new token
  4. Gradually roll out to production
  5. Monitor for issues for 24-48 hours
  6. Revoke old token after confirmation
  7. Update documentation with rotation date
Emergency rotation:
  1. Immediately revoke compromised token
  2. Create replacement token
  3. Deploy emergency update to all services
  4. Notify team of incident
  5. Investigate how compromise occurred
  6. Update procedures to prevent recurrence
mapboxgl.accessToken = mapboxToken;
undefined

Monitoring and Auditing

令牌轮换策略

Track Token Usage

何时轮换令牌

Metrics to monitor:
  • API request volume per token
  • Geographic distribution of requests
  • Error rates by token
  • Unexpected spike patterns
  • Requests from unauthorized domains
Alert on:
  • Usage from unexpected IPs/regions
  • Sudden traffic spikes (>200% normal)
  • High error rates (>10%)
  • Requests outside allowed URLs
  • Off-hours access patterns
强制轮换场景：
  • 令牌暴露在公开代码库中
  • 有权限访问令牌的团队成员离职
  • 怀疑令牌已被泄露或入侵
  • 服务已停用
  • 合规要求
定期轮换场景：
  • 每90天一次（生产环境推荐）
  • 每30天一次（高安全要求环境）
  • 重大部署后
  • 安全审计期间

Regular Security Audits

轮换流程

Monthly checklist:
  • Review all active tokens
  • Verify token scopes are still appropriate
  • Check for unused tokens (revoke if inactive >30 days)
  • Confirm URL restrictions are current
  • Review team member access
  • Check for tokens in public repositories (GitHub scan)
  • Verify documentation is up-to-date
Quarterly checklist:
  • Rotate production tokens
  • Full token inventory
  • Access control review
  • Update incident response procedures
  • Security training for team
零停机轮换：
  1. 创建新令牌，配置与旧令牌相同的权限范围
  2. 部署新令牌到金丝雀/预发布环境
  3. 验证新令牌的功能正常
  4. 逐步推广到生产环境
  5. 监控24-48小时，确认无问题
  6. 确认无误后吊销旧令牌
  7. 更新文档，记录轮换日期
紧急轮换：
  1. 立即吊销泄露的令牌
  2. 创建替代令牌
  3. 紧急更新所有使用该令牌的服务
  4. 通过事件通知渠道告知团队
  5. 调查泄露原因
  6. 更新流程防止再次发生

Common Security Mistakes

监控与审计

1. Exposing Secret Tokens in Client Code

跟踪令牌使用情况

❌ CRITICAL ERROR:
javascript
// NEVER DO THIS - Secret token in client code
const map = new mapboxgl.Map({
  accessToken: 'sk.YOUR_SECRET_TOKEN_HERE' // SECRET TOKEN
});
✅ Correct:
javascript
// Public token only in client code
const map = new mapboxgl.Map({
  accessToken: 'pk.YOUR_PUBLIC_TOKEN_HERE' // PUBLIC TOKEN
});
需要监控的指标：
  • 每个令牌的API请求量
  • 请求的地理分布
  • 各令牌的错误率
  • 异常的流量峰值
  • 来自未授权域名的请求
需要触发告警的场景：
  • 来自意外IP/地区的请求
  • 流量突增（超过正常水平200%）
  • 高错误率（超过10%）
  • 来自未授权URL的请求
  • 非工作时间的访问模式

2. Overly Permissive Scopes

定期安全审计

❌ Too broad:
json
{
  "scopes": ["styles:*", "tokens:*"]
}
✅ Specific:
json
{
  "scopes": ["styles:read"]
}
月度检查清单：
  • 审核所有活跃令牌
  • 验证令牌的权限范围是否仍合适
  • 检查未使用的令牌（超过30天未使用则吊销）
  • 确认URL限制是最新的
  • 审核团队成员的访问权限
  • 检查公开代码库中是否有暴露的令牌（GitHub扫描）
  • 验证文档是否为最新版本
季度检查清单：
  • 轮换生产环境令牌
  • 完成令牌全面盘点
  • 访问控制审核
  • 更新事件响应流程
  • 为团队提供安全培训

3. Missing URL Restrictions

常见安全错误

—

1. 在客户端代码中暴露保密令牌

❌ No restrictions:
json
{
  "scopes": ["styles:read"],
  "allowedUrls": [] // Token works anywhere
}
✅ Domain restricted:
json
{
  "scopes": ["styles:read"],
  "allowedUrls": ["https://myapp.com/*"]
}
❌ 严重错误：
javascript
undefined

4. Long-Lived Tokens Without Rotation

绝对不要这样做 - 客户端代码中包含保密令牌

❌ Never rotated:
Token created: Jan 2020
Last rotation: Never
Still in production: Yes
✅ Regular rotation:
Token created: Dec 2024
Last rotation: Dec 2024
Next rotation: Mar 2025
const map = new mapboxgl.Map({ accessToken: 'sk.YOUR_SECRET_TOKEN_HERE' // 保密令牌 });

✅ **正确做法：**

```javascript

5. Tokens in Version Control

客户端代码仅使用公开令牌

❌ Committed to Git:
javascript
// config.js (committed to repo)
export const MAPBOX_TOKEN = 'sk.YOUR_SECRET_TOKEN_HERE';
✅ Environment variables:
javascript
// config.js
export const MAPBOX_TOKEN = process.env.MAPBOX_SECRET_TOKEN;
bash
undefined
const map = new mapboxgl.Map({ accessToken: 'pk.YOUR_PUBLIC_TOKEN_HERE' // 公开令牌 });
undefined

.env (in .gitignore)

2. 权限范围过于宽泛

MAPBOX_SECRET_TOKEN=sk.YOUR_SECRET_TOKEN_HERE
undefined
❌ 范围过宽：
json
{
  "scopes": ["styles:*", "tokens:*"]
}
✅ 范围具体：
json
{
  "scopes": ["styles:read"]
}

Incident Response Plan

3. 缺少URL限制

If a Token is Compromised

—
Immediate actions (first 15 minutes):
  1. Revoke the token via Mapbox dashboard or API
  2. Create replacement token with different scopes/restrictions if needed
  3. Update all services using the compromised token
  4. Notify team via incident channel
Investigation (within 24 hours): 5. Review access logs to understand exposure 6. Check for unauthorized usage in Mapbox dashboard 7. Identify root cause (how was it exposed?) 8. Document incident with timeline and impact
Prevention (within 1 week): 9. Update procedures to prevent recurrence 10. Implement additional safeguards (CI checks, secret scanning) 11. Train team on lessons learned 12. Update documentation with new security measures
❌ 无限制：
json
{
  "scopes": ["styles:read"],
  "allowedUrls": [] // 令牌可在任意位置使用
}
✅ 域名限制：
json
{
  "scopes": ["styles:read"],
  "allowedUrls": ["https://myapp.com/*"]
}

Best Practices Summary

4. 长期令牌未轮换

Security Checklist

—
Token Creation:
  • Use public tokens for client-side, secret for server-side
  • Apply principle of least privilege for scopes
  • Add URL restrictions to public tokens
  • Use descriptive names/notes for token identification
  • Document intended use and environment
Token Management:
  • Store secret tokens in environment variables or secret managers
  • Never commit tokens to version control
  • Rotate tokens every 90 days (or per policy)
  • Remove unused tokens promptly
  • Separate tokens by environment (dev/staging/prod)
Monitoring:
  • Track token usage patterns
  • Set up alerts for unusual activity
  • Regular security audits (monthly)
  • Review team access quarterly
  • Scan repositories for exposed tokens
Incident Response:
  • Documented revocation procedure
  • Emergency contact list
  • Rotation process documented
  • Post-incident review template
  • Team training on security procedures
❌ 从未轮换：
令牌创建时间：2020年1月
上次轮换时间：从未轮换
仍在生产环境使用：是
✅ 定期轮换：
令牌创建时间：2024年12月
上次轮换时间：2024年12月
下次轮换时间：2025年3月

When to Use This Skill

5. 令牌存储在版本控制系统中

Invoke this skill when:
  • Creating new tokens
  • Deciding between public vs secret tokens
  • Setting up token restrictions
  • Implementing token rotation
  • Investigating security incidents
  • Conducting security audits
  • Training team on token security
  • Reviewing code for token exposure
❌ 提交到Git：
javascript
// config.js（已提交到代码库）
export const MAPBOX_TOKEN = 'sk.YOUR_SECRET_TOKEN_HERE';
✅ 使用环境变量：
javascript
// config.js
export const MAPBOX_TOKEN = process.env.MAPBOX_SECRET_TOKEN;
bash
undefined
—

.env文件（已加入.gitignore）

—
MAPBOX_SECRET_TOKEN=sk.YOUR_SECRET_TOKEN_HERE
undefined
—

事件响应计划

—

令牌泄露后的处理

—
立即行动（前15分钟）：
  1. 吊销令牌：通过Mapbox控制台或API
  2. 创建替代令牌：如有需要，配置不同的权限范围/限制
  3. 更新所有使用该令牌的服务
  4. 通过事件渠道告知团队
调查（24小时内）： 5. 查看访问日志，了解泄露情况 6. 在Mapbox控制台检查是否有未授权使用 7. 确定根本原因（令牌是如何泄露的？） 8. 记录事件，包括时间线和影响范围
预防措施（1周内）： 9. 更新流程，防止再次发生 10. 实施额外防护措施（CI检查、密钥扫描） 11. 为团队提供培训，分享经验教训 12. 更新文档，添加新的安全措施
—

最佳实践总结

—

安全检查清单

—
令牌创建：
  • 客户端使用公开令牌，服务端使用保密令牌
  • 权限范围遵循最小权限原则
  • 为公开令牌添加URL限制
  • 为令牌设置描述性名称/备注，便于识别
  • 记录令牌的预期用途和所属环境
令牌管理：
  • 将保密令牌存储在环境变量或密钥管理器中
  • 绝对不要将令牌提交到版本控制系统
  • 每90天轮换一次令牌（或按策略执行）
  • 及时删除未使用的令牌
  • 按环境（开发/预发布/生产）分离令牌
监控：
  • 跟踪令牌使用模式
  • 为异常活动设置告警
  • 定期进行安全审计（月度）
  • 每季度审核团队访问权限
  • 扫描代码库，检查是否有暴露的令牌
事件响应：
  • 记录令牌吊销流程
  • 准备紧急联系人列表
  • 记录令牌轮换流程
  • 准备事后复盘模板
  • 为团队提供安全流程培训
—

何时使用本技能

—
在以下场景调用本技能：
  • 创建新令牌时
  • 选择使用公开令牌还是保密令牌时
  • 配置令牌限制时
  • 实施令牌轮换策略时
  • 调查安全事件时
  • 进行安全审计时
  • 为团队提供令牌安全培训时
  • 检查代码中是否有令牌暴露时