9a4198eb28
Most of the corpus — FindSet/SetLoadFields/CalcFields patterns, permission sets, SingleInstance codeunits, DataClassification, IsolatedStorage, transaction scope, SecretText — describes BC platform behaviour that is identical across supported versions. The seed [26..28] range on every file implied a version-specificity the content does not actually have, and there was no way to express "applies to every version" in the schema the way [w1] and [all] already do for countries and application-area. Extend the v1 schema with a universal sentinel for bc-version, parallel to the sentinels already defined for the other dimensions: bc-version: [all] # applies to every BC version [all] is mutually exclusive with explicit versions. Range shorthand ([26..28]) and explicit lists ([26, 27, 28]) continue to work for files genuinely tied to a version-gated API or deprecation. Update read.md (field definition, matching semantics, partial-context rule), write.md (default to [all], use ranges only with a concrete reason), README.md (frontmatter example), and the CI validator. All forty existing knowledge files and the three action skills convert to [all]; none of the current content is version-gated. Validator passes.
1.9 KiB
| bc-version | domain | keywords | technologies | countries | application-area | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
security |
|
|
|
|
Prefer OAuth2 over API keys for external HTTP calls
Seed article. Ported from BC Code Intelligence to seed the community corpus. Community contributors are invited to expand or refine.
Description
External HTTP integrations from AL can authenticate using OAuth 2.0 (client-credentials for service-to-service, authorization-code for user-delegated), API keys, basic authentication, or credentials in URLs. The mechanisms differ substantially in the blast radius of a leaked secret and in how cleanly tokens can be rotated. OAuth-issued tokens expire on their own schedule and rotate cleanly; API keys and basic-auth passwords typically have to be rotated manually and usually live unencrypted in a configuration table. When the partner supports OAuth, the difference is a material security improvement, not a stylistic preference.
Best Practice
When the partner supports OAuth, use the platform OAuth2 codeunit (AcquireTokenWithClientCredentials for service-to-service, AcquireAuthorizationCodeTokenFromCache for user-delegated flows) rather than hand-rolled token acquisition. Carry tokens and client secrets as SecretText, persist them only in IsolatedStorage, and refresh tokens proactively — on a buffer before the documented expiry — so routine calls never block on a token refresh.
See sample: prefer-oauth2-over-api-keys-for-external-http-calls.good.al.
Anti Pattern
Accepting an API-key or basic-auth integration because it is the first option documented, even when the partner supports OAuth. The shared secret usually ends up in a setup-table Text field, rotation becomes a manual operation that rarely happens, and a single disclosure exposes every tenant using the extension.
See sample: prefer-oauth2-over-api-keys-for-external-http-calls.bad.al.