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.
Configuration Path
Section titled “Configuration Path”HAKOM:Security:AuthenticationConfiguration Structure
Section titled “Configuration Structure”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)Quick Start
Section titled “Quick Start”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>OpenIdConnect
{ "Security": { "Authentication": { "IdentityProviders": { "IdentityProvider": { "HAKOM": { "Name": "HAKOM", "Type": "OpenIdConnect", "NameClaimType": "name", "RoleClaimType": "groups", "Authority": "https://login.microsoftonline.com/ba990d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0", "ClientId": "f4525fce-xxxx-xxxxx-xxxx-xxxxxxxxxxxx", "Scope": [ "openid", "profile", "email" ] } } } } }}For the exact requirements of the OpenIdConnect Identity Provider look at its official documentation.
Bearer
{ "Security": { "Authentication": { "IdentityProviders": { "IdentityProvider": { "PowerTSM": { "Name": "PowerTSM", "Type": "Bearer", "NameClaimType": "name", "RoleClaimType": "groups", "Authority": "https://login.microsoftonline.com/ba990d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0", "Audience": "f4525fce-xxxx-xxxxx-xxxx-xxxxxxxxxxxx" } } } } }}For the exact requirements of a Bearer Token look at the official documentation.
LocalWindowsUser
{ "Security": { "Authentication": { "IdentityProviders": { "IdentityProvider": { "CurrentUser": { "Name": "CurrentUser", "Type": "LocalWindowsUser", "ClaimTransformations": { "ClaimTransformation": [ { "FromType": "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid", "ToType": "sub", "RetainOriginal": true } ] } } } } } }}Static
{ "Security": { "Authentication": { "IdentityProviders": { "IdentityProvider": { "TestUser": { "Name": "TestUser", "Type": "Static", "Identity": { "Issuer": "Unknown", "NameClaimType": "preferred_username", "RoleClaimType": "roles", "Claims": { "Claim": [ { "Type": "sub", "Value": "0" }, { "Type": "preferred_username", "Value": "username" }, { "Type": "roles", "Value": "Administrator" } ] } } } } } } }}Anonymous
{ "Security": { "Authentication": { "IdentityProviders": { "IdentityProvider": { "NoAuthentication": { "Name": "NoAuthentication", "Type": "Anonymous" } } } } }}OpenIdConnect
HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__Name=HAKOMHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__Type=OpenIdConnectHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__NameClaimType=nameHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__RoleClaimType=groupsHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__Authority=https://login.microsoftonline.com/ba990d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__ClientId=f4525fce-xxxx-xxxxx-xxxx-xxxxxxxxxxxxHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__Scope__0=openidHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__Scope__1=profileHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__HAKOM__Scope__2=emailFor the exact requirements of the OpenIdConnect Identity Provider look at its official documentation.
Bearer
HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__PowerTSM__Name=PowerTSMHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__PowerTSM__Type=BearerHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__PowerTSM__NameClaimType=nameHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__PowerTSM__RoleClaimType=groupsHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__PowerTSM__Authority=https://login.microsoftonline.com/ba990d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__PowerTSM__Audience=f4525fce-xxxx-xxxxx-xxxx-xxxxxxxxxxxxFor the exact requirements of a Bearer Token look at the official documentation.
LocalWindowsUser
HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__CurrentUser__Name=CurrentUserHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__CurrentUser__Type=LocalWindowsUser# Claim transformation exampleHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__CurrentUser__ClaimTransformations__ClaimTransformation__0__FromType=http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysidHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__CurrentUser__ClaimTransformations__ClaimTransformation__0__ToType=subHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__CurrentUser__ClaimTransformations__ClaimTransformation__0__RetainOriginal=trueStatic
HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Name=TestUserHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Type=StaticHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Issuer=UnknownHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__NameClaimType=preferred_usernameHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__RoleClaimType=rolesHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Claims__Claim__0__Type=subHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Claims__Claim__0__Value=0HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Claims__Claim__1__Type=preferred_usernameHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Claims__Claim__1__Value=usernameHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Claims__Claim__2__Type=rolesHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__TestUser__Identity__Claims__Claim__2__Value=AdministratorAnonymous
HAKOM__Security__Authentication__IdentityProviders__IdentityProvider__NoAuthentication__Name=NoAuthenticationHAKOM__Security__Authentication__IdentityProviders__IdentityProvider__NoAuthentication__Type=AnonymousConfiguration Elements
Section titled “Configuration Elements”For details on the behavior or structure of a specific setting, look at their respective external documentation.
Authentication
Section titled “Authentication”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). |
IdentityProvider Options
Section titled “IdentityProvider Options”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
Section titled “OpenIdConnect”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
Section titled “Bearer”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
Section titled “LocalWindowsUser”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
Section titled “Static”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 └─ ValueAnonymous
Section titled “Anonymous”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)ClaimTransformation
Section titled “ClaimTransformation”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. |
Ordering and Matching
Section titled “Ordering and Matching”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
Section titled “ Rename a claim type”Rename a claim type, keeping the value:
<ClaimTransformation> <FromType>OsUsername</FromType> <ToType>os-username</ToType></ClaimTransformation>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>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>Remove a claim
Section titled “ Remove a claim”To remove a claim entirely, match it without specifying ToType, ToValue, or RetainOriginal:
<ClaimTransformation> <FromType>picture</FromType></ClaimTransformation>Identity (Static Type Only)
Section titled “Identity (Static Type Only)”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. |
Verifying the Configuration
Section titled “Verifying the Configuration”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.