OAuth clients (app.OAuthClients)

Summary#

app.OAuthClients declares the third-party OAuth providers your application talks to. There are two reasons to declare one: to let users sign in with an external identity (Login), and to connect to an external API and act on a user's behalf (Connection). Each client is a new OAuthClient("Name") that names a Provider, the Capabilities you need, a ClientId, and a ClientSecret (a Secret.X handle). The client's Name is how the rest of your app refers back to it as OAuthClient.Name.

app.OAuthClients = [
  new OAuthClient("Google") {
    Provider     = OAuthProvider.Google,
    Capabilities = [OAuthCapability.Login],
    ClientId     = "your-client-id",
    ClientSecret = Secret.GoogleOAuth,
  },
];

Signature#

app.Secrets = [ new Secret("GoogleOAuth") ];   // the handle the client below reads

app.OAuthClients = [
  new OAuthClient("Name") {            // one entry per provider client
    Provider     = OAuthProvider.Google,          // Google | Github | Microsoft | Oidc
    Capabilities = [OAuthCapability.Login, OAuthCapability.Connection],
    ClientId     = "your-client-id",              // the provider-issued client id
    ClientSecret = Secret.GoogleOAuth,            // a Secret.X handle, never a literal
  },
];

app.OAuthClients is a list — an app may declare several clients, one per provider (or several against the same provider for different capabilities).

Description#

An OAuthClient has:

• Provider — an OAuthProvider enum member naming the identity provider: Google, Github, Microsoft, or Oidc (a generic OpenID Connect provider).
• Capabilities — a list of OAuthCapability. Login lets users sign into your app with this provider; Connection lets your app connect to the provider's API and act on a signed-in user's behalf. A client may declare both.
• ClientId — a string: the client identifier the provider issued when you registered your app with it.
• ClientSecret — a Secret.X handle referring to a secret declared in declaring secrets (app.Secrets). You never write the secret value inline; you reference the named secret.

The client's Name (the argument to new OAuthClient("…")) is its handle. That name is how the rest of your app refers back to the client as OAuthClient.Name — for example an OAuthAuth method that signs users in via this provider references the client by its OAuthClient.Name handle.

The capability: use Osyrin.Security.Oauth;#

Per-user OAuth links are a capability, Osyrin.Security.Oauth. Declaring an OAuthClient sets up the provider; the capability adds the per-user side: a UserOAuthLink entity that ties one of your app's users to the identity (and, for a Connection client, the stored tokens) they hold with a provider. The platform writes these links when a user signs in or connects; the use/using gates whether your own code may name and query them.

• use Osyrin.Security.Oauth; in the app { } manifest declares the dependency.
• using Osyrin.Security.Oauth; at the top of a source file imports the UserOAuthLink name so a function or query in that file may reference a user's linked provider identities.

See use for how use (the dependency) and using (the file-level import) differ.

Examples#

Declare the secret, then declare a Google client that lets users sign in:

app.Secrets = [ new Secret("GoogleOAuth") ];

app.OAuthClients = [
  new OAuthClient("Google") {
    Provider = OAuthProvider.Google,
    Capabilities = [OAuthCapability.Login],
    ClientId = "your-client-id",
    ClientSecret = Secret.GoogleOAuth,
  },
];

See also#

• declaring secrets (app.Secrets) — app.Secrets, where the Secret.X used by ClientSecret is declared
• [AuthMethod] — a function an unauthenticated visitor may call — declaring an auth method that signs users in via an OAuthClient
• auth bootstrap (login, before anyone is signed in) — granting the first user their role after an OAuth sign-in
• use — use Osyrin.Security.Oauth; (the dependency) and using Osyrin.Security.Oauth; (the import)