Skip to content

Commit 908be47

Browse files
claveryclavery
authored
feat: add --user-auth flag, AM error guidance, and Account Manager guide (#120)
Add --user-auth flag as a shorthand for --auth-methods implicit on all OAuth commands. Normalize AM auth order to match other commands (client-credentials first). Override catch() in AmCommand to provide contextual role-specific suggestions when authentication fails. Add dedicated Account Manager guide covering authentication options, CI/CD automation, common workflows, and troubleshooting. Remove dead IDE Support sidebar link.
1 parent 59fe546 commit 908be47

File tree

10 files changed

+744
-71
lines changed

10 files changed

+744
-71
lines changed

‎.changeset/user-auth-flag-am-error-guidance.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@salesforce/b2c-tooling-sdk': minor
3+
'@salesforce/b2c-cli': minor
4+
---
5+
6+
Add `--user-auth` flag for simplified browser-based authentication. AM commands now use standard auth method order; enhanced error messages provide role-specific guidance for Account Manager operations.

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@ const guideSidebar = [
4848
text: 'Guides',
4949
items: [
5050
{ text: 'Authentication Setup', link: '/guide/authentication' },
51+
{ text: 'Account Manager', link: '/guide/account-manager' },
5152
{ text: 'Scaffolding', link: '/guide/scaffolding' },
52-
{ text: 'IDE Support', link: '/guide/ide-support' },
5353
{ text: 'Security', link: '/guide/security' },
5454
{ text: 'Storefront Next', link: '/guide/storefront-next' },
5555
],

‎docs/cli/account-manager.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,19 +13,23 @@ These flags are available on all Account Manager commands:
1313
| Flag | Environment Variable | Description |
1414
|------|---------------------|-------------|
1515
| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname (e.g., `account.demandware.com`) |
16+
| `--user-auth` | — | Use browser-based user authentication (implicit OAuth flow) |
1617

1718
## Authentication
1819

1920
Account Manager commands work out of the box using the CLI's built-in public client, which authenticates via browser login (implicit flow). No API client configuration is required for interactive use.
2021

21-
For automation or CI/CD, you can provide your own API client credentials.
22+
For automation or CI/CD, you can provide your own API client credentials. Use `--user-auth` to force browser-based authentication when you have client credentials configured but want to use your user account's roles instead.
2223

23-
### Required Roles
24+
### Required Roles by Subtopic
2425

25-
| Auth Method | Role | Configured On |
26-
|-------------|------|---------------|
27-
| Built-in client (default) | Uses your user account's roles | Your user account |
28-
| Client Credentials | `User Administrator` or higher | The API client |
26+
Different Account Manager operations require different roles depending on the authentication method:
27+
28+
| Subtopic | Client Credentials (roles on API client) | User Auth / built-in client (roles on user) |
29+
|----------|------------------------------------------|---------------------------------------------|
30+
| `users`, `roles` | User Administrator | Account Administrator or User Administrator |
31+
| `orgs` | Not supported — use `--user-auth` | Account Administrator |
32+
| `clients` | Not supported — use `--user-auth` | Account Administrator or API Administrator |
2933

3034
### Configuration
3135

@@ -37,6 +41,9 @@ b2c am users list
3741
export SFCC_CLIENT_ID=my-client-id
3842
export SFCC_CLIENT_SECRET=my-client-secret
3943
b2c am users list
44+
45+
# Force browser-based login even with client credentials configured
46+
b2c am users list --user-auth
4047
```
4148

4249
---

‎docs/guide/account-manager.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
---
2+
description: Managing Account Manager users, roles, organizations, and API clients with the B2C CLI — including authentication options, CI/CD automation, and common workflows.
3+
---
4+
5+
# Account Manager Guide
6+
7+
The B2C CLI provides commands for managing Account Manager resources — users, roles, organizations, and API clients — directly from the terminal. This guide covers authentication setup, common workflows, and CI/CD automation.
8+
9+
::: tip
10+
For the full command reference with all flags and options, see [Account Manager Commands](/cli/account-manager).
11+
:::
12+
13+
## Authentication
14+
15+
Account Manager commands work out of the box — no configuration required. The CLI uses a built-in public client that authenticates via browser login. For automation, you can provide your own API client credentials.
16+
17+
### Zero-Config (Default)
18+
19+
Just run commands. The CLI opens a browser for login using the built-in client:
20+
21+
```bash
22+
# Works immediately — opens browser for login
23+
b2c am users list
24+
b2c am orgs list
25+
```
26+
27+
Your user account's roles determine what operations you can perform (see [Role Requirements](#role-requirements)).
28+
29+
### User Authentication (`--user-auth`)
30+
31+
When you have client credentials configured but want browser-based login instead, use `--user-auth`:
32+
33+
```bash
34+
# Force browser login even with SFCC_CLIENT_SECRET set
35+
b2c am users list --user-auth
36+
37+
# Manage organizations (requires user auth)
38+
b2c am orgs list --user-auth
39+
```
40+
41+
### Client Credentials
42+
43+
Uses the API client's secret for non-interactive authentication. Best for CI/CD pipelines, scripts, and automation.
44+
45+
```bash
46+
# List users with client credentials
47+
b2c am users list --client-id $SFCC_CLIENT_ID --client-secret $SFCC_CLIENT_SECRET
48+
```
49+
50+
Requirements:
51+
- A `--client-id` and `--client-secret`
52+
- The API client must have the appropriate roles assigned (see [Role Requirements](#role-requirements))
53+
54+
### Authentication Order
55+
56+
By default, the CLI tries client credentials first (if `--client-secret` is provided), then falls back to browser-based user authentication (using either your configured `--client-id` or the built-in public client). To force browser-based login, pass `--user-auth`.
57+
58+
### Role Requirements
59+
60+
Different operations require different roles, and the required roles depend on how you authenticate:
61+
62+
| Operations | Client Credentials (roles on API client) | User Auth (roles on user account) |
63+
|---|---|---|
64+
| Users & Roles | User Administrator | Account Administrator or User Administrator |
65+
| Organizations | Not supported — use `--user-auth` | Account Administrator |
66+
| API Clients | Not supported — use `--user-auth` | Account Administrator or API Administrator |
67+
68+
::: warning
69+
Organization and API client management are **only available with user authentication**. Client credentials do not support these operations regardless of the roles assigned.
70+
:::
71+
72+
If authentication fails, the CLI provides contextual error messages recommending the specific roles or `--user-auth` flag needed for the operation you attempted.
73+
74+
## Setting Up Credentials
75+
76+
### For Interactive Use
77+
78+
No setup required. Account Manager commands use the CLI's built-in public client by default:
79+
80+
```bash
81+
b2c am users list
82+
```
83+
84+
If you need to use your own API client (for specific scopes or organization restrictions):
85+
86+
1. In [Account Manager](https://account.demandware.com), find or create an API client
87+
2. Under **Redirect URLs**, add `http://localhost:8080`
88+
3. Under **Allowed Scopes**, add: `mail roles tenantFilter openid`
89+
4. Set **Default Scopes** to: `mail roles tenantFilter openid`
90+
91+
```bash
92+
export SFCC_CLIENT_ID=your-client-id
93+
b2c am users list --user-auth
94+
```
95+
96+
### For CI/CD and Automation
97+
98+
1. In [Account Manager](https://account.demandware.com), create a dedicated API client
99+
2. Set a strong password (client secret) and save it securely
100+
3. Set **Token Endpoint Auth Method** to `client_secret_post`
101+
4. Under **Roles**, add **User Administrator** (for user/role management)
102+
5. Under **Allowed Scopes**, add: `mail roles tenantFilter openid`
103+
6. Set **Default Scopes** to: `mail roles tenantFilter openid`
104+
105+
Then configure your CI/CD environment:
106+
107+
```bash
108+
export SFCC_CLIENT_ID=your-client-id
109+
export SFCC_CLIENT_SECRET=your-client-secret
110+
```
111+
112+
::: tip
113+
Store the client secret in your CI/CD system's secrets manager — never commit it to source control.
114+
:::
115+
116+
## Common Workflows
117+
118+
### User Onboarding
119+
120+
Create a user, then grant them the necessary roles:
121+
122+
```bash
123+
# Create the user
124+
b2c am users create --org $ORG_ID --mail developer@example.com \
125+
--first-name Alex --last-name Developer
126+
127+
# Grant Business Manager Admin role scoped to a specific tenant
128+
b2c am roles grant developer@example.com \
129+
--role bm-admin --scope zzxy_prd
130+
```
131+
132+
### User Offboarding
133+
134+
Revoke roles and disable the user:
135+
136+
```bash
137+
# Revoke all roles
138+
b2c am roles revoke developer@example.com --role bm-admin
139+
140+
# Soft delete (disable) the user
141+
b2c am users delete developer@example.com
142+
143+
# Permanent deletion (user must be in DELETED state first)
144+
b2c am users delete developer@example.com --purge
145+
```
146+
147+
### Auditing
148+
149+
Review users, roles, and organization activity:
150+
151+
```bash
152+
# List all users
153+
b2c am users list --extended
154+
155+
# Get user details with expanded roles and organizations
156+
b2c am users get developer@example.com --expand-all
157+
158+
# View organization audit logs
159+
b2c am orgs audit $ORG_ID
160+
```
161+
162+
### API Client Provisioning
163+
164+
Create and configure API clients for your team or automation:
165+
166+
```bash
167+
# Create an API client
168+
b2c am clients create \
169+
--name "CI/CD Pipeline" \
170+
--organizations $ORG_ID \
171+
--password "SecureP@ssword123" \
172+
--roles SALESFORCE_COMMERCE_API \
173+
--role-tenant-filter "SALESFORCE_COMMERCE_API:zzxy_prd"
174+
175+
# Activate the client
176+
b2c am clients update $CLIENT_ID --active
177+
```
178+
179+
### Bulk Operations with JSON Output
180+
181+
Use `--json` output for scripting and integration with other tools:
182+
183+
```bash
184+
# Export all users as JSON
185+
b2c am users list --size 4000 --json
186+
187+
# Export all organizations
188+
b2c am orgs list --all --json
189+
190+
# Pipe to jq for filtering
191+
b2c am users list --json | jq '.[] | select(.userState == "ACTIVE")'
192+
```
193+
194+
## CI/CD Examples
195+
196+
### GitHub Actions
197+
198+
```yaml
199+
jobs:
200+
manage-users:
201+
runs-on: ubuntu-latest
202+
steps:
203+
- uses: actions/checkout@v4
204+
- uses: actions/setup-node@v4
205+
with:
206+
node-version: 22
207+
- run: npm install -g @salesforce/b2c-cli
208+
- run: b2c am users list --json
209+
env:
210+
SFCC_CLIENT_ID: ${{ secrets.SFCC_CLIENT_ID }}
211+
SFCC_CLIENT_SECRET: ${{ secrets.SFCC_CLIENT_SECRET }}
212+
```
213+
214+
### Shell Script Automation
215+
216+
```bash
217+
#!/bin/bash
218+
# Ensure a user has the required roles
219+
220+
USER_EMAIL="developer@example.com"
221+
REQUIRED_ROLES=("bm-admin" "SALESFORCE_COMMERCE_API")
222+
TENANT="zzxy_prd"
223+
224+
for role in "${REQUIRED_ROLES[@]}"; do
225+
echo "Granting $role to $USER_EMAIL..."
226+
b2c am roles grant "$USER_EMAIL" --role "$role" --scope "$TENANT" --json
227+
done
228+
```
229+
230+
## Troubleshooting
231+
232+
### "operation forbidden" or "authentication invalid"
233+
234+
The CLI will suggest the specific role or auth method needed. Common fixes:
235+
236+
- **For user/role operations with client credentials**: Add the **User Administrator** role to your API client, or switch to `--user-auth`
237+
- **For organization operations**: Use `--user-auth` — org management requires user authentication
238+
- **For API client operations**: Use `--user-auth` with a user that has the **Account Administrator** or **API Administrator** role
239+
240+
### "No valid auth method available"
241+
242+
The CLI could not find credentials for any allowed auth method:
243+
244+
- Verify `--client-id` is set (or `SFCC_CLIENT_ID` environment variable)
245+
- For client credentials, verify `--client-secret` is set
246+
- For `--user-auth`, only `--client-id` is required
247+
248+
### Redirect URL errors with `--user-auth`
249+
250+
If the browser login fails with a redirect error:
251+
252+
- In Account Manager, verify `http://localhost:8080` is in the API client's **Redirect URLs**
253+
- Ensure port 8080 is not in use by another application
254+
255+
## Next Steps
256+
257+
- [Account Manager Commands](/cli/account-manager) — Full command reference
258+
- [Authentication Setup](/guide/authentication) — General authentication configuration
259+
- [Configuration](/guide/configuration) — Environment variables and config files

‎docs/guide/authentication.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,13 +39,17 @@ The CLI supports two authentication methods:
3939

4040
| Method | When Used | Role Configuration |
4141
|--------|-----------|-------------------|
42-
| **User Authentication** | When only `--client-id` is provided (no secret) | Roles configured on your **user account** |
42+
| **User Authentication** | When `--user-auth` is passed, or when only `--client-id` is provided (no secret) | Roles configured on your **user account** |
4343
| **Client Credentials** | When both `--client-id` and `--client-secret` are provided | Roles configured on the **API client** |
4444

45-
**User Authentication** opens a browser for interactive login and uses roles assigned to your user account. This is ideal for development and manual operations.
45+
**User Authentication** opens a browser for interactive login and uses roles assigned to your user account. This is ideal for development and manual operations. Use `--user-auth` as a shorthand for `--auth-methods implicit` on any OAuth command.
4646

4747
**Client Credentials** uses the API client's secret for non-interactive authentication. This is ideal for CI/CD pipelines and automation.
4848

49+
::: tip
50+
For Account Manager operations that require user-level roles (organization and API client management), use `--user-auth` to authenticate with your user account. See [Account Manager Authentication](/cli/account-manager#authentication) for per-subtopic role requirements.
51+
:::
52+
4953
### Creating an API Client
5054

5155
1. Log in to [Account Manager](https://account.demandware.com)

0 commit comments

Comments
 (0)