Identity

Sign users in and authenticate requests with OpenID Connect, LDAP, API keys, built-in users, or your own provider.
Framework Docs Menu

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).

Token Checks a value sent with each request (OnAuthenticate)
API keysTokenOIDC Bearer
Redirect Sends the user to an external sign-in page and handles the way back (OnChallenge, OnHandleCallback)
OpenID Connect
Credentials Checks a username and password from the Instance's sign-in page (OnSignIn)
LDAP
Identity User ID, name, and roles (ex. operators), kept in an encrypted cookie for interactive sign-ins
Security Profiles Map roles to permissions on APIs, Apps, and Services
A provider can combine features; return NoResult() when a request isn't meant for it so other providers can try.

Included Providers

ProviderDescription
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.IdentitySigns users in with an OpenID Connect server (ex. Microsoft Entra ID, Okta, Keycloak) and accepts its Bearer tokens.
TrakHound.Ldap.IdentitySigns users in with a username and password verified by an LDAP server (ex. Active Directory), with roles from their groups.
TrakHound.Token.IdentityAuthenticates 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), 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).

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.

ParameterPage
signInProduct, signInLogoThe Instance's form, with a product name and logo. signInLogo is a path that doesn't require signing in, ex. _init/assets/logo.svg
signInPageA 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
signInRouteA 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:

FeatureImplementDescription
TokenOnAuthenticateVerifies a header or query value sent with each request.
RedirectOnChallenge, OnHandleCallbackSends the user to an external sign-in page and handles the redirect back (ex. OpenID Connect).
CredentialsOnSignInVerifies 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.