# Identity

> Sign users in and authenticate requests with OpenID Connect, LDAP, API keys, built-in users, or your own provider.

URL: https://www.trakhound.com/docs/trakhound-framework/identity

An Identity provider signs people in and authenticates requests for the Instance's security profiles. Providers are added and configured under **Security > Providers** in the admin UI, and which resources require which roles is managed with security profiles (see [Security](https://www.trakhound.com/docs/trakhound-framework/security)).

Diagram: Identity providers sign people in three ways. Token providers, such as API keys and the Token provider, check a value sent with each request. Redirect providers, such as OpenID Connect, send the user to an external sign-in page and handle the redirect back. Credentials providers, such as LDAP, check a username and password from the sign-in page. Each produces an identity with a user ID and roles, which security profiles map to permissions.

## Included Providers

| Provider | Description |
| --- | --- |
| **API Keys** (built in) | Accepts hashed keys created under **Security > API Keys**, sent as an `X-API-Key` header or a `Bearer` token. |
| **Users** (built in) | Signs users in with a username and password kept on the Instance, managed under **Security > Users** (see [Users](https://www.trakhound.com/docs/trakhound-framework/identity#users)). |
| `TrakHound.Oidc.Identity` | Signs users in with an OpenID Connect server (ex. Microsoft Entra ID, Okta, Keycloak) and accepts its Bearer tokens. |
| `TrakHound.Ldap.Identity` | Signs users in with a username and password verified by an LDAP server (ex. Active Directory), with roles from their groups. |
| `TrakHound.Token.Identity` | Authenticates requests using a static token, for integrations. |

Interactive providers (OpenID Connect, LDAP, and the built-in Users provider) sign users in at `/_identity/signin` and issue an encrypted cookie session. Use **Test Sign In** on the Providers page to check a configuration. For OpenID Connect, the page shows the Redirect URI to register with your provider.

### Users

The built-in Users provider (ID `users`) is for Apps that only need a few users or have low security needs, with no identity server to run. For single sign-on, MFA, or many users, use OpenID Connect or LDAP.

1. On **Security > Users**, click **Add User** with a username, an optional name, a password (at least 8 characters), and roles.
2. On **Config > Security Profiles**, add a profile with the `users` Identity provider and Assignments that grant those roles permissions on the App or API.
3. People open the App and sign in on the Instance's sign-in page, with the same lockout as other providers.

- Usernames match without regard to case and can't be renamed. Users can't change their own password; an admin sets it with **Edit**.
- Changing a user's password or roles, disabling them, or deleting them ends their sessions on their next request. **Sign Out** on a user's row, or **Sign Out All**, ends sessions without changing anything else. API keys, other providers, and the admin UI keep their sessions.
- **Sign In Page** on the Users page sets the same `signInProduct`, `signInLogo`, and `signInRoute` values as a configured provider (see [Sign In Page](https://www.trakhound.com/docs/trakhound-framework/identity#sign-in-page)), and **Preview** opens it.
- Each user is a file in the configuration profile's `security/users` folder with a salted PBKDF2 hash of the password, never the password. On Linux and macOS only the Instance's user can read them.

### OpenID Connect Parameters

`authority`, `clientId`, `clientSecret`, `scopes`, `rolesClaim`, `userIdClaim`, `nameClaim`, `audience`, and `requireHttpsMetadata`.

### LDAP Parameters

`server`, `port`, `useSsl`, `startTls`, `bindDnFormat`, `serviceBindDn`, `serviceBindPassword`, `searchBase`, `userFilter`, `groupAttribute`, `nameAttribute`, and `roleFormat`.

### Token Identity

`TrakHound.Token.Identity` authenticates a request when the token it sends in the `token` header (or query parameter) matches the configured token. The session is created for the configured `userId` and `roles`:

```
parameters:
  userId: integration-user
  roles: integrations
  token: [a long random value]
```

> Secret parameters such as `token`, `clientSecret`, and `serviceBindPassword` are encrypted when the configuration is saved (see [Configuration](https://www.trakhound.com/docs/trakhound-framework/configuration#secrets)).

## Create an Identity Provider

```
dotnet new trakhound.identity
```

The template creates a provider that inherits from `TrakHoundIdentityProviderBase`:

```
using TrakHound.Clients;
using TrakHound.Security;
using TrakHound.Variables;
using TrakHound.Volumes;

public class Module : TrakHoundIdentityProviderBase
{
    public Module(ITrakHoundIdentityProviderConfiguration configuration, ITrakHoundClient client, ITrakHoundVolume volume, ITrakHoundVariableCollection variables)
        : base(configuration, client, volume, variables) { }

    public override TrakHoundIdentityProviderFeatures Features => TrakHoundIdentityProviderFeatures.Token;

    protected override Task<TrakHoundIdentityResult> OnAuthenticate(TrakHoundIdentityContext context)
    {
        // Use a header unique to this provider (other providers may also read the Authorization header)
        var token = context.Request.GetHeader("X-Example-Token");
        if (string.IsNullOrEmpty(token)) return Task.FromResult(TrakHoundIdentityResult.NoResult());

        // Verify the token, then return the identity. Roles are mapped to permissions by security profile assignments
        var identity = new TrakHoundIdentity();
        identity.UserId = "user";
        identity.Roles = new[] { "operators" };
        return Task.FromResult(TrakHoundIdentityResult.Success(identity));
    }
}
```

### Sign In Page

A provider with `Credentials` uses the Instance's username and password form unless its configuration's parameters choose another page. The page only displays the form: it always posts to the Instance, which checks the antiforgery token and applies the delay and lockout, then calls `OnSignIn`.

| Parameter | Page |
| --- | --- |
| `signInProduct`, `signInLogo` | The Instance's form, with a product name and logo. `signInLogo` is a path that doesn't require signing in, ex. `_init/assets/logo.svg` |
| `signInPage` | A static page in the provider's Package: a folder under `dist` with an `index.html` that uses tokens such as `{{action}}`, `{{error}}`, and `{{antiforgeryToken}}`, so it doesn't need JavaScript |
| `signInRoute` | A page in an App (ex. `/sign-in`), which must be public. It gets the form's values as query parameters, and its form must be a plain `<form method="post">` |

- A page that can't be used logs a warning to the `security` log and the Instance's form is shown, so a mistake can't stop everyone from signing in. Sign ins and failures are written to the same log.
- Each page of an App is a Resource named after its class, `app:{appId}:{class}`, shown on the App's page in the Explorer. To make one page public when a profile covers the whole App, add a profile with no `providerId` that names it, and check the result on **Security > What is Public?**

```
id: my-app-public
description: Pages that don't require signing in
assignments:
- id: sign-in
  resourceId: app:my-app:MyApp.Pages.SignIn
```

### Features

`Features` declares how sign-in works. A provider can combine them:

| Feature | Implement | Description |
| --- | --- | --- |
| `Token` | `OnAuthenticate` | Verifies a header or query value sent with each request. |
| `Redirect` | `OnChallenge`, `OnHandleCallback` | Sends the user to an external sign-in page and handles the redirect back (ex. OpenID Connect). |
| `Credentials` | `OnSignIn` | Verifies a username and password from the Instance's sign-in page (ex. LDAP). |

Implement `OnSignOut` if needed. Return `TrakHoundIdentityResult.Success(identity)`, `NoResult()` (the request isn't for this provider), `Fail(message)`, or `Error(message)`. Read provider settings with `Configuration.GetParameter(name)`.

The template's `Program.cs` runs the provider without an Instance: `dotnet run -- <token>` authenticates a request with the token, and `dotnet run -- <username> <password>` calls `OnSignIn`. The `TrakHound.Token.Identity`, `TrakHound.Ldap.Identity`, and `TrakHound.Oidc.Identity` source code are complete examples.
