Authentication Development Details

Developer Architecture Notes#

Authentication Architecture#

Polaris separates authentication into two logical phases using Quarkus Security:

  1. Credential extraction – parsing headers and tokens
  2. Credential authentication – validating identity and assigning roles

Key Interfaces#

  • Authenticator: A core interface used to authenticate credentials and resolve principal and principal roles. Roles may be derived from OIDC claims or internal mappings.

  • InternalPolarisToken: Used in internal auth and inherits from PrincipalCredential.

  • The DefaultAuthenticator is used to implement realm-specific logic based on these abstractions.

Token Broker Configuration#

When internal authentication is enabled, Polaris uses TokenBroker to handle the decoding and validation of authentication tokens. These brokers are request-scoped and can be configured per realm. Each realm may use its own strategy, such as RSA key pairs or shared secrets, depending on security requirements. See Token Broker description for configuration details.

Developer Authentication Workflows#

Internal Authentication#

  1. InternalAuthenticationMechanism parses the auth header.
  2. Uses TokenBroker to decode the token.
  3. Builds InternalAuthenticationRequest and generates SecurityIdentity (Quarkus).
  4. Authenticator.authenticate() validates the credential, resolves the principal and principal roles, then creates the PolarisPrincipal.

External Authentication#

  1. OidcAuthenticationMechanism (Quarkus) processes the auth header.
  2. OidcTenantResolvingAugmentor selects the OIDC tenant.
  3. OidcPolarisCredentialAugmentor extracts JWT claims.
  4. Authenticator.authenticate() validates the claims, resolves the principal and principal roles, then creates the PolarisPrincipal.

Mixed Authentication#

  1. InternalAuthenticationMechanism tries decoding.
  2. If successful, proceed with internal authentication.
  3. Otherwise, fall back to external (OIDC) authentication.

OIDC Configuration Reference#

Principal Mapping#

  • Interface: PrincipalMapper

    The PrincipalMapper is responsible for extracting the Polaris principal ID and display name from OIDC tokens.

  • Implementation selector:

    This property selects the implementation of the PrincipalMapper interface. The default implementation extracts fields from specific claim paths.

    polaris.oidc.principal-mapper.type=default

  • Configuration properties for the default implementation:

    polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id 
polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name

  • It can be overridden per OIDC tenant.

Roles Mapping#

  • Interface: PrincipalRolesMapper

    Polaris uses this component to transform role claims from OIDC tokens into Polaris roles.

  • Quarkus OIDC configuration:

    This setting instructs Quarkus on where to locate roles within the OIDC token.

    quarkus.oidc.roles.role-claim-path=polaris/roles

  • Implementation selector:

    This property selects the implementation of PrincipalRolesMapper. The default implementation applies regular expression (regex) transformations to OIDC roles.

    polaris.oidc.principal-roles-mapper.type=default

  • Configuration properties for the default implementation:

    polaris.oidc.principal-roles-mapper.filter=^(?!profile$|email$).* 
polaris.oidc.principal-roles-mapper.mappings[0].regex=^.*$ 
polaris.oidc.principal-roles-mapper.mappings[0].replacement=PRINCIPAL_ROLE:$0