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).
OnAuthenticate)
OnChallenge, OnHandleCallback)
OnSignIn)
operators), kept in an encrypted cookie for interactive sign-insNoResult() when a request isn't meant for it so other providers can try.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). |
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.
- On Security > Users, click Add User with a username, an optional name, a password (at least 8 characters), and roles.
- On Config > Security Profiles, add a profile with the
usersIdentity provider and Assignments that grant those roles permissions on the App or API. - 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, andsignInRoutevalues as a configured provider (see Sign In Page), and Preview opens it. - Each user is a file in the configuration profile's
security/usersfolder 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]
token, clientSecret, and serviceBindPassword are encrypted when the configuration is saved
(see Configuration).
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
securitylog 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 noproviderIdthat 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.