# OAuth clients (app.OAuthClients)

> `app.OAuthClients` declares the third-party OAuth providers your app uses — for signing users in (Login) and for connecting to an external API on a user's behalf (Connection). Each is `new OAuthClient("Name")` naming a Provider (Google/Github/Microsoft/Oidc), the Capabilities, a ClientId, and a ClientSecret (a `Secret.X` handle). Referenced elsewhere by its `OAuthClient.Name` handle.

<!-- id: config-oauth-clients · area: config · stability: stable · html: https://osysharp.com/reference/config/oauth-clients/ -->

## Summary        {#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`.

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

## Signature      {#signature}
```osy
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    {#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)](https://osysharp.com/reference/config/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 Osysharp.Security.Oauth;`     {#capability}
Per-user OAuth links are a **capability**, `Osysharp.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 Osysharp.Security.Oauth;`** in the `app { }` manifest declares the dependency.
- **`using Osysharp.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](https://osysharp.com/reference/types/use/) for how `use` (the dependency) and `using` (the file-level import) differ.

## Examples       {#examples}
Declare the secret, then declare a Google client that lets users sign in:

```osy title="basic" test app=config-oauth-example
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       {#see-also}
- [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — `app.Secrets`, where the `Secret.X` used by `ClientSecret` is declared
- [[AuthMethod] — a function an unauthenticated visitor may call](https://osysharp.com/reference/security/auth-method/) — declaring an auth method that signs users in via an `OAuthClient`
- [auth bootstrap (login, before anyone is signed in)](https://osysharp.com/reference/security/auth-bootstrap/) — granting the first user their role after an OAuth sign-in
- [use](https://osysharp.com/reference/types/use/) — `use Osysharp.Security.Oauth;` (the dependency) and `using Osysharp.Security.Oauth;` (the import)