salesforce-auth
Skill1 starsChanged 3 months agoMITView on GitHub
Use when authenticating tests to a Salesforce org — JWT bearer flow, sf CLI tokens, injecting a session into the browser, handling mandatory MFA or SSO, and producing one storageState per persona. Load before writing any Salesforce UI test.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- ai-native-workflowSkill
- api-testingSkill
- bootstrapSkill
- common-tasksSkill
- configSkill
- data-strategySkill
- debuggingSkill
- enumsSkill
- fixturesSkill
- page-objectsSkill
- salesforce-dataSkill
- salesforce-locatorsSkill
- salesforce-metadata-contractSkill
- salesforce-personasSkill
- salesforceSkill
- salesforce-waitsSkill
- security-testingSkill
- selectorsSkill
- test-standardsSkill
- type-safetySkill
- wait-strategySkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Do this once and record it in PROJECT.md.
- Very specific: line 47
Put the consumer key in SF_CLIENT_ID and the _contents_ of server.key in SF_JWT_PRIVATE_KEY (or a path in SF_JWT_KEY_PATH).
- Very specific: line 94
If the org is SSO-only for humans, that does not affect you: the JWT bearer flow bypasses the IdP entirely because it authenticates the …
- Distinctive: line 147
Don't automate the login form or an MFA challenge.
- Distinctive: line 148
Don't generate TOTP codes in test code.
- Very specific: line 150
Don't hardcode instance_url — sandbox refreshes and org migrations change it.
- Distinctive: line 152
Don't reuse a session across personas.
- Very specific: line 153
Don't log the access token.
- Very specific: line 154
Don't commit server.key, SF_JWT_PRIVATE_KEY, or any .auth/*.json.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Salesforce Auth — never automate the login form
Salesforce login is the single largest source of flake in Salesforce suites: it is slow, it is MFA-gated, it may be SSO-redirected, and it rate-limits. The fix is to stop driving it. Mint a session over the API, then hand that session to the browser.
The model
1. JWT bearer flow (server-to-server) → access_token + instance_url
2. Inject that session into a browser context
3. Save storageState → every UI test starts logged inStep 1 is MFA-exempt by design — the JWT bearer flow is an OAuth flow for trusted server-to-server integration; there is no interactive challenge to satisfy. This is not a workaround, it is the supported path for automation.
Getting a session
helpers/salesforce/auth.ts implements three strategies. Pick by environment.
| Strategy | Use for | Needs |
jwt | CI (default) | Connected App: consumer key + RSA private key + username |
sfdx | Local dev | sf CLI authenticated to the org; just an alias |
password | Last resort | username + password + security token; MFA must be off |
jwt needs no new dependency — Node's built-in crypto signs the RS256 assertion.
Setting up the Connected App (one-time, per org)
Do this once and record it in PROJECT.md. It is org configuration, so a human with Setup access has
to do it — you cannot script your way in.
- Generate a key pair:
openssl req -x509 -newkey rsa:2048 -nodes -keyout server.key -out server.crt -subj "/CN=pw-tests" -days 730 - Setup → App Manager → New Connected App → enable OAuth, upload
server.crt, enable Use digital signatures, scopes:api,refresh_token,web. - Manage → Edit Policies → Permitted Users = Admin approved users are pre-authorized.
- Assign the app to a Profile or Permission Set that your test users hold. This step is the one
everyone forgets — without it the flow returns
invalid_grant: user hasn't approved this consumer. - Put the consumer key in
SF_CLIENT_IDand the contents ofserver.keyinSF_JWT_PRIVATE_KEY(or a path inSF_JWT_KEY_PATH). Never commit either.
password is a trap
Username-password OAuth requires MFA to be disabled for that user, and Salesforce has been progressively removing that possibility. It also silently appends a security token requirement that changes whenever the password changes. Support it for a legacy org, but don't build on it.
Injecting the session into the browser
Two mechanisms. They depend on org settings, so verify which works in your org before committing to
one (see docs/salesforce/VERIFY-BEFORE-FIRST-RUN.md).
// A. Session cookie injection — preferred. No navigation to a login endpoint at all.
await context.addCookies([
{
name: 'sid',
value: accessToken,
domain: new URL(instanceUrl).hostname,
path: '/',
httpOnly: true,
secure: true,
sameSite: 'None',
},
]);
// B. frontdoor.jsp — the classic fallback.
await page.goto(
`${instanceUrl}/secur/frontdoor.jsp?sid=${accessToken}&retURL=${encodeURIComponent(ret)}`,
);Caveats you must know:
frontdoor.jspis being restricted. Salesforce has shipped release updates that limit passing a session id tofrontdoor.jsp. Treat B as a fallback and expect it to stop working; prefer A.- "Lock sessions to the IP address from which they originated" (Setup → Session Settings) breaks both if your API call and browser egress from different IPs. In CI they usually match; through a proxy they may not. If auth mysteriously 302s to login, check this setting first.
- My Domain matters. The cookie domain must be the instance host the session belongs to
(
https://acme--uat.sandbox.my.salesforce.com), not the Lightning host (...lightning.force.com). Useinstance_urlfrom the token response verbatim — don't construct it.
SSO orgs
If the org is SSO-only for humans, that does not affect you: the JWT bearer flow bypasses the IdP
entirely because it authenticates the Connected App, not the browser session. This is the main reason
to prefer jwt over anything interactive. Do not attempt to script an IdP login page.
One storageState per persona
Salesforce assertions are always "for whom" (see salesforce-personas), so the auth setup fans out:
// helpers/salesforce/personas.setup.ts — one setup test per persona
for (const persona of PERSONAS) {
setup(`authenticate ${persona.key}`, async ({ browser }) => {
const session = await getOrgSession(persona.key);
const context = await browser.newContext();
await applySession(context, session);
await context.storageState({ path: storageStateFor(persona.key) });
await context.close();
});
}Each persona's state lands at .auth/<environment>/sf-<persona>.json. UI projects declare which one
they default to; a test needing a different persona uses the asPersona fixture.
Three details that matter:
- The path is namespaced by
ENVIRONMENT, not just by persona. Run this against dev, then staging, and each keeps its own state — without the environment segment, the second run would either silently overwrite the first's file or (worse) a stale dev session would get handed to a staging test, which fails in a way that looks like an auth bug rather than an environment mixup. - The fan-out iterates
UI_PERSONAS, not all of them. An API-only identity (uiCapable: false, e.g. an integration user) has no UI licence, so building a browser session for it fails for a perfectly correct reason and would block the whole run. - The UI default is
standardUser, not an admin.SF_ADMIN_PERSONA(arrange/teardown) andSF_DEFAULT_PERSONA(the subject) are deliberately separate env vars. A UI test running as System Admin exercises a screen no real user sees and bypasses sharing and FLS — seesalesforce-personas.
Never reuse one persona's context for another persona's assertions. Cached Lightning state and cached org metadata will make the test pass alone and fail in the suite.
Verify the session actually worked
A failed injection presents as "logged out", which then looks like a locator bug thirty lines later. Assert it once, in setup, before saving state:
await page.goto(LightningRoutes.HOME);
// A real Lightning shell is present only when authenticated.
await expect(page.getByRole('button', { name: 'App Launcher' })).toBeVisible();Don't
- Don't automate the login form or an MFA challenge.
- Don't generate TOTP codes in test code. It's feasible and it's still wrong — it moves the MFA secret into your CI and produces a test that fails at clock skew.
- Don't hardcode
instance_url— sandbox refreshes and org migrations change it. Read it from the token response. - Don't reuse a session across personas.
- Don't log the access token. It is a live session id.
helpers/salesforce/auth.tsredacts it. - Don't commit
server.key,SF_JWT_PRIVATE_KEY, or any.auth/*.json.
Checklist
- Strategy chosen per environment (
jwtin CI). - Connected App assigned to the test users' profile/permset (step 4 above).
- Session injected, not typed into a form.
instance_urlread from the token response.- One
storageStateper UI-capable persona, verified with a post-auth assertion. SF_ADMIN_PERSONA(arrange) andSF_DEFAULT_PERSONA(subject) both set, and the subject is NOT an admin.- No token in logs, no key in git.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

