Skip to main content

JSON Web Tokens

Summary​

HR Suit uses signed JSON Web Tokens (JWTs) as access tokens and separate opaque refresh tokens for obtaining a new token pair without repeating password authentication.

Audience​

  • Implementation and support teams
  • Developers and QA engineers
  • DevOps engineers
  • Solution architects and security engineers

Purpose​

The access token carries verified identity and access context to downstream applications. The refresh token supports controlled renewal through server-side validation, rotation, and revocation records.

Architecture​

Business concepts​

  • Access token: a signed, time-bounded credential presented to protected APIs.
  • Refresh token: an opaque credential exchanged only through the refresh flow and stored server-side as a hash.
  • Claims: identity and access facts carried by the access token.
  • Tenant claims: tenant identifiers used by tenant-aware applications; platform accounts can have no tenant assignment.
  • Token validation: verification of token integrity, accepted issuer/audience configuration, validity period, and application requirements.

Technical implementation​

Confirmed access-token claims include a subject/user identity, email, portal type, roles, permissions, tenant identity when assigned, and employee identity when linked. Compatibility identity fields are also emitted during the transition between monolith and extracted services.

Downstream ASP.NET Core services configure JWT bearer validation and derive an authenticated principal from accepted tokens. Authorization then evaluates the principal rather than trusting unvalidated request content.

Refresh tokens are generated separately, hashed before persistence, associated with a user and optionally a device session, and rotated during successful refresh. This page intentionally omits token durations, signing implementation details, key identifiers, configuration names, and secret material.

Confirmed source references​

  • microservices/src/identity-service/Application/Security/IdentityJwtTokenService.cs
  • microservices/src/identity-service/Application/Security/IdentityRefreshTokenService.cs
  • microservices/src/identity-service/Application/Security/AccessTokenRequest.cs
  • microservices/src/identity-service/Domain/Entities/RefreshToken.cs
  • microservices/src/identity-service/Program.cs

See Also​

Keywords​

  • Bearer authentication
  • Tenant claims
  • Token integrity

Revision Information​

  • Last reviewed: 2026-07-14
  • Owner: identity-team
  • Status: Draft