Authentication

Policies and personas describe who may do what — but an application also has to say how its users sign in. The top level authentication block declares the identity providers of the application, so the sign-in surface is part of the same declaration as everything else.

Additional typed information about the caller belongs in the separate top-level identity block, not under authentication. Both blocks are authoring metadata, not ESM behavior.

Syntax

authentication
  provider <Name> [name <Alias>]
  ...

• authentication — top level, alongside concepts, policies and personas. At most one block per document; a second one is a compile error.
• provider <Name> — one entry per identity provider, naming which provider it is: EntraId, GitHub, Google, Apple, OpenId.
• name <Alias> — what this provider goes by. Optional, and only needed when the provider alone does not identify it.

Example

authentication
  provider EntraId
  provider GitHub
  provider Google
  provider Apple

Naming a provider

A generic provider can appear more than once. Two OpenId providers are two different identity providers, and nothing about the word OpenId tells them apart — so give them names:

authentication
  provider OpenId name Partner
  provider OpenId name Supplier

A provider must be distinguishable: two entries that resolve to the same name are a compile error. Where no alias is given, the provider name is the name.

What a provider deliberately does not carry

A provider says which identity provider the application signs users in with. It says nothing about how to reach one — no authority, no client id, no secret.

That is not an omission. Authority URLs, client ids and the credentials that go with them are what running the application needs to know, not what the application is, and they differ per environment while the document does not. A document that carried them would be a different document in test and in production, which is the opposite of what it is for.

Configuration lines under a provider are therefore a compile error rather than something quietly ignored — a document that states them is saying something the language does not express, and hiding that would be worse than reporting it.

A runtime such as Stage resolves the configuration itself. Provider identities are realization metadata, not part of the executable semantic model (ESM). A renderer can get them from a successful syntax compilation result:

var parsed = new ScreenplayCompiler().Compile(source);
if (parsed.Success)
{
    var providers = parsed.Value!.Authentication?.Providers;
    // Use each provider's Name, Alias, or Identity to select host configuration.
}
else
{
    // Report parsed.Diagnostics; do not render an invalid document.
}

Each AuthenticationProviderSyntax has Name, optional Alias, and Identity (alias if present, otherwise name). The compiler’s visitors can traverse the same syntax. SemanticModelCompiler.Compile(...) returns a SemanticCompilation with Model, Documents, and SourceMap, but no typed provider companion view: a renderer receiving only that result must parse its source documents separately to obtain provider declarations. There is currently no lossless, provider-typed semantic compilation companion API; do not infer provider identities from ESM. How the runtime stores provider configuration — a secret store, environment variables, or another host mechanism — is its own business.