forcedotcom/sf-skills / skills/external-diagram-mermaid-generate
external-diagram-mermaid-generate
UnverifiedSalesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says "diagram", "visualize", "ERD", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user asks about non-Salesforce systems.
assets/oauth/jwt-bearer.md
View on GitHub# JWT Bearer Flow Template
OAuth 2.0 JWT Bearer assertion flow for server-to-server authentication without user interaction.
## When to Use
- Server-to-server integrations
- CI/CD pipelines
- Scheduled jobs and automation
- Background processes
- Any headless authentication scenario
## Prerequisites
1. X.509 Certificate uploaded to Salesforce Connected App
2. Pre-authorized user via Permission Set
3. Private key securely stored on server
## Mermaid Template
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {
'actorBkg': '#ddd6fe',
'actorTextColor': '#1f2937',
'actorBorder': '#6d28d9',
'signalColor': '#334155',
'signalTextColor': '#1f2937',
'noteBkgColor': '#f8fafc',
'noteTextColor': '#1f2937',
'noteBorderColor': '#334155'
}}}%%
sequenceDiagram
autonumber
box rgba(221,214,254,0.3) SERVER ENVIRONMENT
participant S as š„ļø Server<br/>(CI/CD, Backend)
participant K as š Key Store
end
box rgba(167,243,208,0.3) SALESFORCE
participant SF as āļø Salesforce<br/>Authorization Server
end
Note over S,SF: JWT Bearer Flow (RFC 7523)
S->>K: 1. Retrieve Private Key
K->>S: 2. Return Private Key
S->>S: 3. Create JWT Header
Note over S: {<br/> "alg": "RS256",<br/> "typ": "JWT"<br/>}
S->>S: 4. Create JWT Payload
Note over S: {<br/> "iss": "CONSUMER_KEY",<br/> "sub": "user@company.com",<br/> "aud": "https://login.salesforce.com",<br/> "exp": CURRENT_TIME + 300<br/>}
S->>S: 5. Sign JWT with Private Key
Note over S: signature = RS256(header.payload, privateKey)<br/>jwt = header.payload.signature
S->>SF: 6. POST /services/oauth2/token
Note over S,SF: grant_type=urn:ietf:params:oauth:<br/> grant-type:jwt-bearer<br/>assertion=SIGNED_JWT
SF->>SF: 7. Decode JWT
SF->>SF: 8. Validate Signature
Note over SF: Verify using uploaded<br/>X.509 certificate
SF->>SF: 9. Validate Claims
Note over SF: ⢠iss matches Consumer Key<br/>⢠sub is pre-authorized user<br/>⢠aud is correct endpoint<br/>⢠exp is not passed
SF->>SF: 10. Check User Authorization
Note over SF: User must be pre-authorized<br/>via Permission Set
SF->>S: 11. Return Access Token
Note over SF,S: {<br/> "access_token": "...",<br/> "instance_url": "https://...",<br/> "token_type": "Bearer",<br/> "issued_at": "...",<br/> "scope": "api"<br/>}
Note over S: ā ļø No refresh_token returned
S->>S: 12. Store Access Token
S->>SF: 13. Make API Calls
Note over S,SF: Authorization: Bearer ACCESS_TOKEN
SF->>S: 14. API Response
```
## ASCII Fallback Template
```text
āāāāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāā
ā Server/CI/CD ā ā Salesforce ā
ā (Private Key) ā ā (Certificate) ā
āāāāāāāāāāāāā¬āāāāāāāāāāāā āāāāāāāāāāā¬āāāāāāāāāāā
ā ā
ā 1. Create JWT Claims ā
ā iss: consumer_key ā
ā sub: user@company.com ā
ā aud: login.sf.com ā
ā exp: now + 5 min ā
ā ā
ā 2. Sign JWT with ā
ā Private Key (RS256) ā
ā ā
ā 3. POST /token ā
ā (grant_type=jwt-bearer)
ā (assertion=signed_jwt)ā
āāāāāāāāāāāāāāāāāāāāāāāāāāā>ā
ā ā
ā 4. Verify JWT ā
ā signature ā
ā with cert ā
ā ā
ā 5. Validate ā
ā claims ā
ā ā
ā 6. Check user ā
ā pre-auth ā
ā ā
ā 7. Access Token ā
ā (NO refresh token!) ā
ā<āāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā 8. API Request ā
ā (Bearer token) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāā>ā
ā ā
ā 9. API Response ā
ā<āāāāāāāāāāāāāāāāāāāāāāāāāāā
```
## JWT Structure
### Header
```json
{
"alg": "RS256",
"typ": "JWT"
}
```
### Payload (Claims)
```json
{
"iss": "3MVG9...", // Consumer Key from Connected App
"sub": "user@company.com", // Pre-authorized username
"aud": "https://login.salesforce.com", // Or test.salesforce.com for sandbox
"exp": 1702123456 // Expiration (current time + 5 min max)
}
```
### Signature
```text
RS256(
base64URLEncode(header) + "." + base64URLEncode(payload),
privateKey
)
```
## Token Request
```bash
curl -X POST https://login.salesforce.com/services/oauth2/token \
-d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
-d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIzTVZHOS4uLiIsInN1YiI6InVzZXJAY29tcGFueS5jb20iLCJhdWQiOiJodHRwczovL2xvZ2luLnNhbGVzZm9yY2UuY29tIiwiZXhwIjoxNzAyMTIzNDU2fQ.SIGNATURE"
```
## Code Examples
### Python
```python
import jwt
import time
import requests
private_key = open('server.key').read()
claim_set = {
'iss': 'YOUR_CONSUMER_KEY',
'sub': 'user@company.com',
'aud': 'https://login.salesforce.com',
'exp': int(time.time()) + 300 # 5 minutes
}
assertion = jwt.encode(claim_set, private_key, algorithm='RS256')
response = requests.post(
'https://login.salesforce.com/services/oauth2/token',
data={
'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
'assertion': assertion
}
)
access_token = response.json()['access_token']
instance_url = response.json()['instance_url']
```
### Node.js
```javascript
const jwt = require('jsonwebtoken');
const axios = require('axios');
const fs = require('fs');
const privateKey = fs.readFileSync('server.key');
const token = jwt.sign(
{
iss: 'YOUR_CONSUMER_KEY',
sub: 'user@company.com',
aud: 'https://login.salesforce.com',
exp: Math.floor(Date.now() / 1000) + 300
},
privateKey,
{ algorithm: 'RS256' }
);
const response = await axios.post(
'https://login.salesforce.com/services/oauth2/token',
new URLSearchParams({
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion: token
})
);
const { access_token, instance_url } = response.data;
```
## Key Characteristics
| Aspect | Value |
|--------|-------|
| User Interaction | None required |
| Refresh Token | **Not returned** - re-authenticate with new JWT |
| Token Lifetime | Default ~2 hours (configurable) |
| Security Model | Certificate-based (asymmetric) |
| Audience | `login.salesforce.com` or `test.salesforce.com` |
## Security Considerations
1. **Protect private key** - Use secrets manager, HSM, or secure vault
2. **Rotate certificates** before expiration
3. **Short JWT expiration** - Maximum 5 minutes recommended
4. **Limit user permissions** - Use dedicated integration user
5. **Monitor token usage** - Set up login history alerts
## Troubleshooting
| Error | Cause | Solution |
|-------|-------|----------|
| `invalid_grant` | JWT expired or invalid | Check exp claim, verify signature |
| `invalid_client` | Consumer key mismatch | Verify iss matches Connected App |
| `user_not_authorized` | User not pre-approved | Assign Permission Set to user |
| `invalid_assertion` | Signature verification failed | Verify certificate upload |
## Customization Points
Replace these placeholders:
- `CONSUMER_KEY` ā Your Connected App's Consumer Key
- `user@company.com` ā Pre-authorized Salesforce username
- `login.salesforce.com` ā Or `test.salesforce.com` for sandbox
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why ā repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" ā or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself ā your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |