Authentication
This page describes how to configure authentication for Polaris when deploying with the Helm chart.
Overview🔗
Polaris supports three authentication modes:
| Mode | Type | Description |
|---|---|---|
| Internal | internal | Polaris manages credentials and issues tokens. Default mode. |
| External | external | An external Identity Provider (IDP) issues tokens. Polaris validates them via OIDC. |
| Mixed | mixed | Both internal and external authentication are enabled. |
For more information on authentication in Polaris, see the Identity Providers section of the documentation.
Internal Authentication🔗
Internal authentication is the default mode. Polaris manages user credentials and issues JWT tokens using either an RSA key pair or a symmetric key.
⚠️ Warning
In a multi-replica production environment, all Polaris pods must share the same token signing keys. The default chart generates random keys for each pod, which will cause token validation failures.RSA Key Pair (Recommended)🔗
RSA key pairs provide asymmetric encryption, allowing public key distribution for token verification.
Generate an RSA key pair and create a Kubernetes secret:
1openssl genrsa -out private.pem 2048
2openssl rsa -in private.pem -pubout -out public.pem
3
4kubectl create secret generic polaris-token-keys \
5 --namespace polaris \
6 --from-file=private.pem \
7 --from-file=public.pem
Configure the chart to use the RSA key pair:
1authentication:
2 type: internal
3 tokenBroker:
4 type: rsa-key-pair
5 secret:
6 name: "polaris-token-keys"
7 rsaKeyPair:
8 publicKey: "public.pem"
9 privateKey: "private.pem"
Symmetric Key🔗
Symmetric keys use the same secret for both signing and verification.
Generate a symmetric key and create a Kubernetes secret:
1openssl rand -base64 32 > symmetric.key
2
3kubectl create secret generic polaris-token-keys \
4 --namespace polaris \
5 --from-file=symmetric.key
Configure the chart:
1authentication:
2 type: internal
3 tokenBroker:
4 type: symmetric-key
5 secret:
6 name: "polaris-token-keys"
7 symmetricKey:
8 secretKey: "symmetric.key"
Token Lifetime🔗
Configure the maximum token lifetime:
1authentication:
2 tokenBroker:
3 maxTokenGeneration: PT1H # 1 hour (ISO 8601 duration)
External Authentication (OIDC)🔗
External authentication delegates token issuance to an external Identity Provider (IDP) that supports OpenID Connect (OIDC). Polaris validates tokens using the IDP’s public keys.
Polaris works with any OIDC-compliant identity provider.
Basic Configuration🔗
To enable external authentication:
1authentication:
2 type: external
3
4oidc:
5 authServeUrl: "https://your-idp.example.com/realms/polaris"
6 client:
7 id: polaris
Configuration with Client Secret🔗
If your IDP requires a client secret for token introspection:
1kubectl create secret generic polaris-oidc-client \
2 --namespace polaris \
3 --from-literal=clientSecret='your-client-secret'
1authentication:
2 type: external
3
4oidc:
5 authServeUrl: "https://your-idp.example.com/realms/polaris"
6 client:
7 id: polaris
8 secret:
9 name: "polaris-oidc-client"
10 key: "clientSecret"
Principal Mapping🔗
Configure how Polaris maps OIDC token claims to Polaris principals:
1oidc:
2 principalMapper:
3 type: default
4 idClaimPath: "sub" # Claim containing the principal ID
5 nameClaimPath: "preferred_username" # Claim containing the principal name
For nested claims, use / as a separator:
1oidc:
2 principalMapper:
3 idClaimPath: "polaris/principal_id"
4 nameClaimPath: "polaris/principal_name"
Role Mapping🔗
Configure how Polaris maps OIDC token claims to Polaris roles:
1oidc:
2 principalRolesMapper:
3 type: default
4 rolesClaimPath: "realm_access/roles" # Path to roles in the token
Role Filtering🔗
Filter which roles from the token are passed to Polaris:
1oidc:
2 principalRolesMapper:
3 filter: "^POLARIS_.*" # Only include roles starting with POLARIS_
Role Name Transformation🔗
Transform role names from the IDP format to Polaris format using regex mappings:
1oidc:
2 principalRolesMapper:
3 mappings:
4 - regex: "^role_(.*)"
5 replacement: "PRINCIPAL_ROLE:$1"
6 - regex: "^admin$"
7 replacement: "PRINCIPAL_ROLE:service_admin"
The default Polaris authenticator expects roles in the format PRINCIPAL_ROLE:<role_name>.
Full Example🔗
1authentication:
2 type: external
3
4oidc:
5 authServeUrl: "https://keycloak.example.com/realms/polaris"
6 client:
7 id: polaris
8 secret:
9 name: "polaris-oidc-client"
10 key: "clientSecret"
11 principalMapper:
12 idClaimPath: "sub"
13 nameClaimPath: "preferred_username"
14 principalRolesMapper:
15 rolesClaimPath: "realm_access/roles"
16 mappings:
17 - regex: "^polaris_(.*)"
18 replacement: "PRINCIPAL_ROLE:$1"
Mixed Authentication🔗
Mixed mode enables both internal and external authentication simultaneously. This is useful during migration from internal to external authentication, or when some clients use internal credentials while others use external tokens.
1authentication:
2 type: mixed
3 tokenBroker:
4 type: rsa-key-pair
5 secret:
6 name: "polaris-token-keys"
7 rsaKeyPair:
8 publicKey: "public.pem"
9 privateKey: "private.pem"
10
11oidc:
12 authServeUrl: "https://your-idp.example.com/realms/polaris"
13 client:
14 id: polaris
Per-Realm Authentication🔗
You can configure different authentication settings for different realms:
1authentication:
2 type: internal # Default for all realms
3 realmOverrides:
4 production:
5 type: external
6 staging:
7 type: mixed
Advanced Configuration🔗
For advanced OIDC configuration not covered by the chart values, use the advancedConfig section to pass Quarkus OIDC properties directly:
1advancedConfig:
2 quarkus.oidc.token.issuer: "https://your-idp.example.com"
3 quarkus.oidc.token.audience: "polaris-api"
4 quarkus.oidc.authentication.scopes: "openid,profile,email"
See the Quarkus OIDC configuration reference for all available options.
Disabling the Token Service🔗
When using external authentication exclusively, you can disable the internal token service:
1authentication:
2 type: external
3 tokenService:
4 type: disabled
This prevents Polaris from issuing tokens and ensures all authentication goes through the external IDP.