# Auth — External Client Apps, OAuth flows, Named and External Credentials

Target: Spring '26. Sources: [New connected apps can no longer be created in Spring '26](https://help.salesforce.com/s/articleView?id=005228017&type=1), [External Client Apps](https://help.salesforce.com/s/articleView?id=platform.external_client_apps_general.htm&type=5), [OAuth flows](https://help.salesforce.com/s/articleView?id=platform.remoteaccess_oauth_flows.htm&type=5), [Named Credentials](https://help.salesforce.com/s/articleView?id=platform.named_credentials_about.htm&type=5).

## 1. App identity: External Client App, not Connected App

- From **Spring '26**, creating a Connected App is disabled by default in orgs, through the UI *and* the Metadata API. Salesforce Support can still grant an exception today; that door is closing.
- Existing Connected Apps keep working, and managed-package installs are unaffected. Every one of them is on a migration path to an **External Client App (ECA)** — inventory them now and migrate the ones you own.
- An ECA splits what used to be one blob into separate metadata: the app itself, its **global** OAuth settings (secrets, callback URLs, flow enablement) and its **policies** (session, IP relaxation, permitted users). That is why ECAs package and deploy cleanly and Connected Apps never did.
- Set up in Setup → **External Client App Manager**. Deploy as metadata like anything else; keep the consumer secret out of the repo (`$Secret`-style references or the pipeline's secret store).

## 2. Choosing the OAuth flow

| Situation | Flow | Notes |
|---|---|---|
| Server-to-server, no human, client can hold a secret | **Client Credentials** | Enable it on the ECA and set the **Run As** integration user. `POST /services/oauth2/token` with `grant_type=client_credentials`, client id and secret. The simplest correct choice for a backend job |
| Server-to-server, no secret at rest, high assurance | **JWT Bearer** | Signed assertion with a certificate you rotate; `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<jwt>`. The user must be pre-authorised for the app |
| A real user acts in an app | **Authorization Code + PKCE** | Mandatory shape for mobile and SPA clients; refresh token policy set deliberately |
| Device with no browser | Device flow | Being retired on Connected Apps — new work goes to an ECA |
| Username-password | **never** | Blocked in most orgs and always the wrong answer |

Rules for all of them: one **integration user per consuming system** (attributable usage, revocable in isolation), API-only where the licence allows, permissions from a permission set rather than a profile, IP relaxation chosen deliberately, and a written rotation date for every secret and certificate.

## 3. Named Credentials and External Credentials (Salesforce calling out)

The pair does the token work so no Apex ever holds a secret:

- **External Credential** — the authentication protocol (OAuth 2.0, JWT, JWT bearer, AWS Signature V4, Basic, or custom headers) plus its **principals**:
  - *Named Principal* — one identity for the whole org (the usual integration case).
  - *Per User Principal* — each user authenticates individually (a user acting on their own behalf in a partner system).
- **Named Credential** — the URL, which External Credential to use, which headers to generate, and whether Apex/Flow may generate headers.
- Access is granted by **permission set**: a user without the External Credential Principal Access on their permission set gets a callout failure, not a login prompt. This is the most common "it works for me" bug.
- In code and flow the endpoint is `callout:ERP_Api/orders/123` — no host, no key, no refresh logic.
- Per-user OAuth credentials for a Per User Principal are authorised from the user's settings; build a short runbook for it rather than explaining it per ticket.

## 4. Inbound users and permissions

```
Integration_ERP (User, API Only profile or minimum-access profile)
  └ Permission Set: ERP_Integration
       Object: Order__c (Create, Read, Edit)  — no Delete
       Field: Order__c.ERP_Id__c (Read, Edit)
       Apex class: OrderApi
       System: API Enabled
       Bypass: Ignore_Validation_Rules__c on the integration user  ← migration windows only
```

- Never reuse a human's account for an integration, and never give the integration user "Modify All Data" because a test failed — find the missing object or field permission instead.
- Freeze rather than delete a retired integration user; its records keep their owner.
- For inbound Apex REST, class access goes on the permission set too — a missing class permission looks like a 403 with no detail.

## 5. Migration checklist — Connected App → ECA

- [ ] Inventory: Setup → Connected Apps OAuth Usage, plus `ConnectedApplication` in the Metadata API and any packaged apps (packaged ones are the vendor's job)
- [ ] For each app you own: which flow, which integration user, which consumers hold the client id/secret
- [ ] Create the ECA with the same flows, scopes and callback URLs; keep the old app live during cutover
- [ ] Re-issue client id/secret to consumers, or re-sign the JWT against the new app
- [ ] Switch one consumer, watch Login History and API usage for that user, then the rest
- [ ] Retire the Connected App only after a full quiet period, and record the date in the integration design document
- [ ] Recheck session and IP policies on the ECA — they are separate metadata and do not carry over silently
