Skip to content
Documentation

Authentication Configuration

This guide describes how to configure authentication for PowerTSM components. The authentication system is highly flexible and supports multiple identity provider types, allowing integration with external services, local accounts, or static test users. You can tailor authentication to your environment by choosing from OpenIdConnect, Bearer, LocalWindowsUser, Static, or Anonymous providers. Each provider type has its own configuration options, and you can combine general and type-specific settings to meet your security requirements.

HAKOM:Security:Authentication
Authentication
├─ DefaultIdentityProvider
├─ IdentifierClaimType
└─ IdentityProviders
└─ IdentityProvider
└─ {Name}
├─ Name (must repeat {Name})
├─ Type
├─ RemoveUntransformedClaims
├─ ClaimTransformations
│ └─ ClaimTransformation (multiple allowed)
│ ├─ FromType
│ ├─ FromValue
│ ├─ ToType
│ ├─ ToValue
│ └─ RetainOriginal
├─ NameClaimType
├─ RoleClaimType
└─ … (type-specific settings)

Depending on the type of the identity provider, different settings have to be configured. Name and Type are always required.

OpenIdConnect

<HAKOM>
<Security>
<Authentication>
<IdentityProviders>
<IdentityProvider Name="HAKOM">
<Type>OpenIdConnect</Type>
<NameClaimType>name</NameClaimType>
<RoleClaimType>groups</RoleClaimType>
<Authority>https://login.microsoftonline.com/ba990d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0</Authority>
<ClientId>f4525fce-xxxx-xxxxx-xxxx-xxxxxxxxxxxx</ClientId>
<Scope>openid</Scope>
<Scope>profile</Scope>
<Scope>email</Scope>
</IdentityProvider>
</IdentityProviders>
</Authentication>
</Security>
</HAKOM>

For the exact requirements of the OpenIdConnect Identity Provider look at its official documentation.

Bearer

<HAKOM>
<Security>
<Authentication>
<IdentityProviders>
<IdentityProvider Name="PowerTSM">
<Type>Bearer</Type>
<NameClaimType>name</NameClaimType>
<RoleClaimType>groups</RoleClaimType>
<Authority>https://login.microsoftonline.com/ba990d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0</Authority>
<Audience>f4525fce-xxxx-xxxxx-xxxx-xxxxxxxxxxxx</Audience>
</IdentityProvider>
</IdentityProviders>
</Authentication>
</Security>
</HAKOM>

For the exact requirements of a Bearer Token look at the official documentation.

LocalWindowsUser

<HAKOM>
<Security>
<Authentication>
<IdentityProviders>
<IdentityProvider Name="CurrentUser">
<Type>LocalWindowsUser</Type>
<ClaimTransformations>
<ClaimTransformation>
<FromType>http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid</FromType>
<ToType>sub</ToType>
<RetainOriginal>true</RetainOriginal>
</ClaimTransformation>
</ClaimTransformations>
</IdentityProvider>
</IdentityProviders>
</Authentication>
</Security>
</HAKOM>

Static

<HAKOM>
<Security>
<Authentication>
<IdentityProviders>
<IdentityProvider Name="TestUser">
<Type>Static</Type>
<Identity>
<Issuer>Unknown</Issuer>
<NameClaimType>preferred_username</NameClaimType>
<RoleClaimType>roles</RoleClaimType>
<Claims>
<Claim>
<Type>sub</Type>
<Value>0</Value>
</Claim>
<Claim>
<Type>preferred_username</Type>
<Value>username</Value>
</Claim>
<Claim>
<Type>roles</Type>
<Value>Administrator</Value>
</Claim>
</Claims>
</Identity>
</IdentityProvider>
</IdentityProviders>
</Authentication>
</Security>
</HAKOM>

Anonymous

<HAKOM>
<Security>
<Authentication>
<IdentityProviders>
<IdentityProvider Name="NoAuthentication">
<Type>Anonymous</Type>
</IdentityProvider>
</IdentityProviders>
</Authentication>
</Security>
</HAKOM>

For details on the behavior or structure of a specific setting, look at their respective external documentation.

Path: HAKOM:Security:Authentication

Element Type Default Required Description
DefaultIdentityProvider string — Name of the identity provider to use when a request carries no authentication information. Required only if more than one provider is configured. Example: HAKOM, PowerTSM, CurrentUser, TestUser, Anonymous.
IdentifierClaimType string sub Claim type that uniquely identifies the authenticated user. Used to resolve the user’s database identifier for ownership and stored authorization rules.
IdentityProviders array — ✓ Collection of all configured identity providers (IdentityProvider entries).

Path: HAKOM:Security:Authentication:IdentityProviders:IdentityProvider:{Name}

Element Type Default Required Description
Name string — ✓ Unique name for the identity provider. Must match the configuration key of the entry. Applies to all types. Example: HAKOM, PowerTSM, CurrentUser, TestUser.
Type enum — ✓ Provider type. Matched case-insensitively. Applies to all types. Allowed values: OpenIdConnect, Bearer, LocalWindowsUser, Static, Anonymous.
RemoveUntransformedClaims bool false Remove claims that were not matched by any entry in ClaimTransformations. Applies to all types.
ClaimTransformations array — List of claim transformation rules (ClaimTransformation entries). Applies to all types. See ClaimTransformation.
NameClaimType string — Claim type that supplies the identity’s primary name. If unset, the provider’s own default is kept. Applies to all types except Static. Example: name, preferred_username.
RoleClaimType string — Claim type that carries the identity’s roles. If unset, the provider’s own default is kept. Applies to all types except Static. Example: groups, roles.
Authority string — ✓ Authority URL of the external provider. Applies to OpenIdConnect and Bearer.
ClientId string — ✓ Client ID (GUID) registered with the provider. Also used as the expected audience. Applies to OpenIdConnect.
Audience string — ✓ Expected audience (GUID) of incoming tokens. Applies to Bearer.
Scope array — ✓ Scopes requested during interactive sign-in. Multiple values allowed. Applies to OpenIdConnect. Example: openid, profile, email.
Identity object — ✓ Static identity configuration. Applies to Static. See Identity (Static Type Only).
{Specific} — — Additional advanced options via OpenIdConnectOptions and JwtBearerOptions. Applies to OpenIdConnect and Bearer.

Type-specific configuration details:

OpenIdConnect uses the OpenID Connect protocol for authentication, typically with an external identity provider (e.g., Azure AD, Google). Requires configuration such as Authority, ClientId, and Scope. Supports advanced options from OpenIdConnectOptions.

Structure:

IdentityProvider
└─ {Name}
├─ Type (OpenIdConnect)
├─ NameClaimType
├─ RoleClaimType
├─ Authority
├─ ClientId
├─ Scope (multiple allowed)
└─ … (other OpenIdConnectOptions properties)

Bearer uses JWT Bearer tokens for authentication, commonly for APIs. Requires settings like Authority and Audience. Supports options from JwtBearerOptions.

Structure:

IdentityProvider
└─ {Name}
├─ Type (Bearer)
├─ NameClaimType
├─ RoleClaimType
├─ Authority
├─ Audience
└─ … (other JwtBearerOptions properties)

LocalWindowsUser authenticates as the Windows account that the process itself runs under. No external provider is required. Useful for service-to-service calls and for the PowerTSM .NET API.

Structure:

IdentityProvider
└─ {Name}
└─ Type (LocalWindowsUser)

Static provides a fixed identity defined directly in the configuration. Useful for testing or scenarios where a hardcoded user is needed. The identity, claims, and issuer are specified in the configuration.

Structure:

IdentityProvider
└─ {Name}
├─ Type (Static)
└─ Identity
├─ Issuer
├─ NameClaimType
├─ RoleClaimType
└─ Claims
└─ Claim (multiple allowed)
├─ Type
└─ Value

Anonymous produces no identity at all: every authentication attempt fails with NotAuthenticatedException, which results in a 401 response without an authentication challenge. Use it to make the absence of authentication explicit.

Structure:

IdentityProvider
└─ {Name}
└─ Type (Anonymous)

Claim transformations map or rename claims from the source identity provider to the claims used by your application. This is useful when the external provider uses different claim types or values than your application expects. For example transforming a Windows SID claim into a standard sub claim, or mapping an opaque group identifier onto a role name.

Path: HAKOM:Security:Authentication:IdentityProviders:IdentityProvider:{Name}:ClaimTransformations:ClaimTransformation

Element Type Default Required Description
FromType string — ✓ Claim type to match. Compared case-sensitively. Example: http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid, groups.
FromValue string — Claim value to match. If unset, every claim of FromType matches. Compared case-sensitively. Example: 8f3c1b2a-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
ToType string — Claim type after transformation. If unset, the type is not changed. Example: sub, role.
ToValue string — Claim value after transformation. If unset, the value is not changed. Example: administrator.
RetainOriginal bool false Keep the original claim in addition to the transformed one.

Transformations are applied in the order in which they appear in the configuration. For each claim, only the first matching transformation is applied. The claim is then left alone. Several transformations may therefore share the same FromType as long as they are distinguished by FromValue. This is the usual way to map several group identifiers onto different roles.

Claims that no transformation matched are kept unchanged, unless RemoveUntransformedClaims is true.

Rename a claim type, keeping the value:

<ClaimTransformation>
<FromType>OsUsername</FromType>
<ToType>os-username</ToType>
</ClaimTransformation>

flask Map a group identifier onto a role

Section titled “ Map a group identifier onto a role”

Map a specific group identifier onto a role name, discarding the original:

<ClaimTransformation>
<FromType>groups</FromType>
<FromValue>8f3c1b2a-xxxx-xxxx-xxxx-xxxxxxxxxxxx</FromValue>
<ToType>role</ToType>
<ToValue>administrator</ToValue>
</ClaimTransformation>

flask Keep the original claim

Section titled “ Keep the original claim”

Keep the original claim alongside the transformed one:

<ClaimTransformation>
<FromType>http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid</FromType>
<ToType>sub</ToType>
<RetainOriginal>true</RetainOriginal>
</ClaimTransformation>

To remove a claim entirely, match it without specifying ToType, ToValue, or RetainOriginal:

<ClaimTransformation>
<FromType>picture</FromType>
</ClaimTransformation>

Path: HAKOM:Security:Authentication:IdentityProviders:IdentityProvider:{Name}:Identity

Element Type Default Required Description
Issuer string — ✓ Issuer recorded on every claim of the static identity. Example: Unknown.
NameClaimType string — ✓ Claim type that supplies the identity’s primary name. Example: preferred_username.
RoleClaimType string — ✓ Claim type that carries the identity’s roles. Example: roles.
Claims array — ✓ List of claims (Claim entries).

Path: HAKOM:Security:Authentication:IdentityProviders:IdentityProvider:{Name}:Identity:Claims:Claim

Element Type Default Required Description
Type string — ✓ Claim type. Example: sub, preferred_username, roles.
Value string — ✓ Claim value. Example: 0, username, Administrator.

The PowerTSM HTTP API exposes two endpoints for checking an authentication configuration:

Endpoint Purpose
GET /identity Returns the resulting identity for the current request: all claims after transformation, plus the effective NameClaimType and RoleClaimType.
GET /identityProviders Lists the identity providers that were successfully configured, with their names, types, and authentication schemes.

GET /identity is the primary diagnostic tool: it shows what actually arrived, which is not necessarily what the identity provider issued. When a claim is missing, comparing the decoded token with the output of this endpoint distinguishes a provider-side problem from a transformation problem.

For interactive providers, GET /identityProviders/{Name}/signin starts the sign-in flow and GET /identity/signout ends the session.

© 2026 Volue.Version v0.6.38017 November 2026