You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "markhoerth (via GitHub)" <gi...@apache.org> on 2025/07/09 00:47:41 UTC
[PR] Add External Identity Providers page to unreleased documentation [polaris]
markhoerth opened a new pull request, #2013:
URL: https://github.com/apache/polaris/pull/2013
<!--
Possible security vulnerabilities: STOP here and contact security@apache.org instead!
Please update the title of the PR with a meaningful message - do not leave it "empty" or "generated"
Please update this summary field:
The summary should cover these topics, if applicable:
* the motivation for the change
* a description of the status quo, for example the current behavior
* the desired behavior
* etc
PR checklist:
- Do a self-review of your code before opening a pull request
- Make sure that there's good test coverage for the changes included in this PR
- Run tests locally before pushing a PR (./gradlew check)
- Code should have comments where applicable. Particularly hard-to-understand
areas deserve good in-line documentation.
- Include changes and enhancements to the documentation (in site/content/in-dev/unreleased)
- For Work In Progress Pull Requests, please use the Draft PR feature.
Make sure to add the information BELOW this comment.
Everything in this comment will NOT be added to the PR description.
-->
Adds a new documentation page explaining how to configure external identity providers for authentication in Apache Polaris.
The page provides setup guidance and examples for using OIDC with external IdPs, and is intended for users configuring authentication settings.
The file was added under `site/content/in-dev/unreleased/...` and will appear in the docs navigation when published.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2193896274
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
Review Comment:
ditto
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
+# Extract the text after "role\_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role\_(.*)
+# Replace the extracted text with "POLARIS\_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
+```
+
+See more examples below.
+
+## Developer Architecture Notes
+
+The following sections describe internal implementation details for developers who want to understand or extend Polaris authentication.
+
+### 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.
+- `DecodedToken`: Used in internal auth and inherits from `PrincipalCredential`.
+- `ActiveRolesProvider`: Resolves the set of roles associated with the authenticated user for the current request. Roles may be derived from OIDC claims or internal mappings.
+
+The `DefaultAuthenticator` (formerly BasePolarisAuthenticator) is used to implement realm-specific logic based on these abstractions.
Review Comment:
Might be nice to link out for `formerly` to the PR that changed it
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
Review Comment:
I noticed that other docs don't reference the file directly, e.g. see this similar excerpt from the metastores doc:
```
Additionally the retries can be configured via `polaris.persistence.relational.jdbc.*` properties please ref [configuration](./configuration.md)
```
Another doc just lists some properties:
```
It is highly recommended to configure Polaris with previously-generated RSA keys. This can be done
by setting the following properties:
```
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
style: `Authenticator` could perhaps be `_authenticator_`, `**authenticator**` or just `authenticator`
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
+# Extract the text after "role\_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role\_(.*)
+# Replace the extracted text with "POLARIS\_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
+```
+
+See more examples below.
+
+## Developer Architecture Notes
+
+The following sections describe internal implementation details for developers who want to understand or extend Polaris authentication.
+
+### Authentication Architecture
+
+Polaris separates authentication into two logical phases using Quarkus Security:
Review Comment:
Might be nice to [link](https://quarkus.io/guides/security-overview) out
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
Review Comment:
```suggestion
- Tries internal authentication first; if this fails, it falls back to OIDC.
```
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
Review Comment:
```suggestion
When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenID Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
```
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
Review Comment:
musing: Seeing `Active Roles Provider` pop up so often, I wonder if it might be helpful to dub this `ARP`
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
If this is referring to a type in the code, it could be helpful to link that code as well
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
Review Comment:
```suggestion
- Multiple realms can share a single OIDC tenant.
```
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
Review Comment:
`(used for scoping users, resources, and policies)`
Realms do more than that (unless all entities are considered "resources" here, in which case "policies" and "users" are redundant). Maybe just link the realm doc?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra merged PR #2013:
URL: https://github.com/apache/polaris/pull/2013
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2200897816
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,341 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if this fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm by setting the following properties:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The [`Authenticator`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/Authenticator.java) is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the `Authenticator` implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The [`ActiveRolesProvider`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/ActiveRolesProvider.java) is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.active-roles-provider.type=default
+```
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The [`TokenBroker`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/TokenBroker.java) signs and verifies tokens to ensure that they can be validated and remain unaltered.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal `TokenBroker`.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service and `TokenServiceConfiguration` (Quarkus) is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the `Authenticator` and `TokenBroker`. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A [realm]({{% ref "realm" %}}) is a logical partition within Polaris.
+
+- Multiple realms can share a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenID Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default `ActiveRolesProvider` expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role_"
+polaris.oidc.principal-roles-mapper.filter=role_.*
+# Extract the text after "role_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role_(.*)
+# Replace the extracted text with "POLARIS_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
Review Comment:
```suggestion
polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on PR #2013:
URL: https://github.com/apache/polaris/pull/2013#issuecomment-3050928760
cc @adutra / @collado-mike for visibility
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195374127
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
Nouns are lower case in English.
(Upper case in German ;) )
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195412062
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
Review Comment:
Thanks for the comment. I added a link to the realm doc page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195441047
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
Review Comment:
I updated this to `ActiveRolesProvider`. Please let me know if that is what you had in mind.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195109522
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
Review Comment:
Apologies, I removed them.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195106963
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
+# Extract the text after "role\_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role\_(.*)
+# Replace the extracted text with "POLARIS\_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
+```
+
+See more examples below.
+
+## Developer Architecture Notes
+
+The following sections describe internal implementation details for developers who want to understand or extend Polaris authentication.
+
+### 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.
+- `DecodedToken`: Used in internal auth and inherits from `PrincipalCredential`.
+- `ActiveRolesProvider`: Resolves the set of roles associated with the authenticated user for the current request. Roles may be derived from OIDC claims or internal mappings.
+
+The `DefaultAuthenticator` (formerly BasePolarisAuthenticator) is used to implement realm-specific logic based on these abstractions.
Review Comment:
I removed the "formerly" phrase. Thanks for the comments.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195329741
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
Hm - not sure a code reference would help end users, especially if the page "gets forgotten" and the Java type's source file possibly moved elsewhere.
So `authenticator` SGTM
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2200911145
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,341 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if this fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm by setting the following properties:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The [`Authenticator`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/Authenticator.java) is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the `Authenticator` implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The [`ActiveRolesProvider`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/ActiveRolesProvider.java) is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.active-roles-provider.type=default
+```
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The [`TokenBroker`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/TokenBroker.java) signs and verifies tokens to ensure that they can be validated and remain unaltered.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal `TokenBroker`.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service and `TokenServiceConfiguration` (Quarkus) is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the `Authenticator` and `TokenBroker`. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A [realm]({{% ref "realm" %}}) is a logical partition within Polaris.
+
+- Multiple realms can share a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenID Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default `ActiveRolesProvider` expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
Review Comment:
```suggestion
The default `ActiveRolesProvider` expects the security identity to expose role names in the following format: `POLARIS_ROLE:<role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195425274
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
Review Comment:
Thanks for the comment, I deleted the without ... clause.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195439146
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
Review Comment:
Thanks Alex, I made these changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2194503081
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
Review Comment:
FYI #2000 was merged yesterday so this section is now outdated. The TLDR is:
* the property was moved to `polaris.authentication.active-roles-provider.type`
* the active roles provider is now also overridable per realm
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
Review Comment:
This sentence ("without ... request") is imho unnecessary. Here, Polaris is both the auth server and the resource server, so I guess it can contact itself :-)
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
Review Comment:
Just curious, why do we need to escape the underscore here?
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
Review Comment:
+1, it's better not to mention this file explicitly since configuration can be done through many different ways (env vars, system props, etc.)
```suggestion
Authentication can be configured globally or per realm by setting the following properties:
```
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
+# Extract the text after "role\_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role\_(.*)
+# Replace the extracted text with "POLARIS\_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
+```
+
+See more examples below.
+
+## Developer Architecture Notes
+
+The following sections describe internal implementation details for developers who want to understand or extend Polaris authentication.
+
+### 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.
+- `DecodedToken`: Used in internal auth and inherits from `PrincipalCredential`.
+- `ActiveRolesProvider`: Resolves the set of roles associated with the authenticated user for the current request. Roles may be derived from OIDC claims or internal mappings.
+
+The `DefaultAuthenticator` (formerly BasePolarisAuthenticator) is used to implement realm-specific logic based on these abstractions.
+
+### Token Broker Configuration
+
+Polaris uses token brokers 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.
Review Comment:
```suggestion
When internal authentication is enabled, Polaris uses token brokers 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.
```
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
+# Extract the text after "role\_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role\_(.*)
+# Replace the extracted text with "POLARIS\_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
+```
+
+See more examples below.
+
+## Developer Architecture Notes
+
+The following sections describe internal implementation details for developers who want to understand or extend Polaris authentication.
+
+### 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.
+- `DecodedToken`: Used in internal auth and inherits from `PrincipalCredential`.
+- `ActiveRolesProvider`: Resolves the set of roles associated with the authenticated user for the current request. Roles may be derived from OIDC claims or internal mappings.
+
+The `DefaultAuthenticator` (formerly BasePolarisAuthenticator) is used to implement realm-specific logic based on these abstractions.
Review Comment:
Or alternatively, remove this "formerly BasePolarisAuthenticator" completely? Docs are versioned, so imo they should focus on what's available currently. No need for historical data.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195750478
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
I think standardizing on `Authenticator` is fine, but preferably we can make that clear that it refers to a specific type by providing the canonical name of the type (or a link to the code/docs).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195427321
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
Review Comment:
Thanks for the comment, I added a link to the realm page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2194506828
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
Review Comment:
This sentence ("without ... request") is imho unnecessary. Here, Polaris is both the auth server and the resource server, so I guess it is in permanent contact with itself :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195417552
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the Authenticator implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The Active Roles Provider is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation to use:
+
+```properties
+polaris.active-roles-provider.type=default
+```
+
+Contrary to the Authenticator, the Active Roles Provider is defined only once for the entire Polaris instance. It is not overridable per realm.
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The Token Broker signs and verifies tokens to ensure that they cannot be tampered with and can be validated without requiring contact with the original issuer on every request.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal Token Broker.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the Authenticator and Token Broker. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A realm is a logical partition within Polaris (used for scoping users, resources, and policies).
+
+- Multiple realms can use a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenId Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default Active Roles Provider expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role\_"
+polaris.oidc.principal-roles-mapper.filter=role\_.*
+# Extract the text after "role\_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role\_(.*)
+# Replace the extracted text with "POLARIS\_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
+```
+
+See more examples below.
+
+## Developer Architecture Notes
+
+The following sections describe internal implementation details for developers who want to understand or extend Polaris authentication.
+
+### Authentication Architecture
+
+Polaris separates authentication into two logical phases using Quarkus Security:
Review Comment:
Thanks, I added a link.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195462021
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
I updated this and the other component names. Please let me know if this is what was intended.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2196201177
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
Hi Eric,
I added a link out to the code.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195380444
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
Certainly, but `Authenticator` is a formal name.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2195358790
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
Below the text uses `Authenticator`. What is the rationale for `authenticator`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "markhoerth (via GitHub)" <gi...@apache.org>.
markhoerth commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2196201177
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,344 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if it fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm in `application.properties`:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The Authenticator is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
Review Comment:
Hi Eric,
I added a link out to the code. Please send me any additional comments.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #2013:
URL: https://github.com/apache/polaris/pull/2013#discussion_r2200613329
##########
site/content/in-dev/unreleased/external-idp.md:
##########
@@ -0,0 +1,341 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+title: External Identity Providers
+type: docs
+weight: 550
+---
+
+Apache Polaris supports authentication via external identity providers (IdPs) using OpenID Connect (OIDC) in addition to the internal authentication system. This feature enables flexible identity federation with enterprise IdPs and allows gradual migration or hybrid authentication strategies across realms in Polaris.
+
+## Authentication Types
+
+Polaris supports three authentication modes:
+
+1. `internal` (Default)
+ - Only Polaris internal authentication is used.
+2. `external`
+ - Authenticates using external OIDC providers (via Quarkus OIDC).
+ - Disables the internal token endpoint (returns HTTP 501).
+3. `mixed`
+ - Tries internal authentication first; if this fails, it falls back to OIDC.
+
+Authentication can be configured globally or per realm by setting the following properties:
+
+```properties
+# Global default
+polaris.authentication.type=internal
+# Per-realm override
+polaris.authentication.realm1.type=external
+polaris.authentication.realm2.type=mixed
+```
+
+## Key Components
+
+### Authenticator
+
+The [`Authenticator`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/Authenticator.java) is a component responsible for creating a Polaris principal from the credentials provided by the authentication process. It is common to all authentication types.
+
+The `type` property is used to define the `Authenticator` implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.authenticator.type=default
+polaris.authentication.realm1.authenticator.type=custom
+```
+
+### Active Roles Provider
+
+The [`ActiveRolesProvider`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/ActiveRolesProvider.java) is a component responsible for determining which roles the principal is requesting and should be activated. It is common to all authentication types.
+
+Only the `type` property is defined; it is used to define the provider implementation. It is overridable per realm:
+
+```properties
+polaris.authentication.active-roles-provider.type=default
+```
+
+## Internal Authentication Configuration
+
+### Token Broker
+
+The [`TokenBroker`](https://github.com/apache/polaris/blob/main/service/common/src/main/java/org/apache/polaris/service/auth/TokenBroker.java) signs and verifies tokens to ensure that they can be validated and remain unaltered.
+
+```properties
+polaris.authentication.token-broker.type=rsa-key-pair
+polaris.authentication.token-broker.max-token-generation=PT1H
+```
+
+Two types are available:
+
+- `rsa-key-pair` (recommended for production): Uses an RSA key pair for token signing and validation.
+- `symmetric-key`: Uses a shared secret for both operations; suitable for single-node deployments or testing.
+
+The property `polaris.authentication.token-broker.max-token-generation` specifies the maximum validity duration of tokens issued by the internal `TokenBroker`.
+
+- Format: ISO-8601 duration (e.g., `PT1H` for 1 hour, `PT30M` for 30 minutes).
+- Default: `PT1H`.
+
+### Token Service
+
+The Token Service and `TokenServiceConfiguration` (Quarkus) is responsible for issuing and validating tokens (e.g., bearer tokens) for authenticated principals when internal authentication is used. It works in coordination with the `Authenticator` and `TokenBroker`. The default implementation is `default`, and this must be configured when using internal authentication.
+
+```properties
+polaris.authentication.token-service.type=default
+```
+
+## External Authentication Configuration
+
+External authentication is configured via Quarkus OIDC and Polaris-specific OIDC extensions. The following settings are used to integrate with an identity provider and extract identity and role information from tokens.
+
+### OIDC Tenant Configuration
+
+At least one OIDC tenant must be explicitly enabled. In Polaris, realms and OIDC tenants are distinct concepts. An OIDC tenant represents a specific identity provider configuration (e.g., `quarkus.oidc.idp1`). A [realm]({{% ref "realm" %}}) is a logical partition within Polaris.
+
+- Multiple realms can share a single OIDC tenant.
+- Each realm can be associated with only one OIDC tenant.
+
+Therefore, multi-realm deployments can share a common identity provider while still enforcing realm-level scoping. To configure the default tenant:
+
+```properties
+quarkus.oidc.tenant-enabled=true
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/polaris
+quarkus.oidc.client-id=polaris
+```
+
+Alternatively, it is possible to use multiple named tenants. Each OIDC-named tenant is then configured with standard Quarkus settings:
+
+```properties
+quarkus.oidc.oidc-tenant1.auth-server-url=http://localhost:8080/realms/polaris
+quarkus.oidc.oidc-tenant1.client-id=client1
+quarkus.oidc.oidc-tenant1.application-type=service
+```
+
+When using multiple OIDC tenants, it's your responsibility to configure tenant resolution appropriately. See the [Quarkus OpenID Connect Multitenany Guide](https://quarkus.io/guides/security-openid-connect-multitenancy#tenant-resolution).
+
+### Principal Mapping
+
+While OIDC tenant resolution is entirely delegated to Quarkus, Polaris requires additional configuration to extract the Polaris principal and its roles from the credentials generated and validated by Quarkus. This part of the authentication process is configured with Polaris-specific properties that map JWT claims to Polaris principal fields:
+
+```properties
+polaris.oidc.principal-mapper.type=default
+polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+These properties are overridable per OIDC tenant:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
+polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
+```
+
+> [!IMPORTANT]: The default implementation of PrincipalMapper can only work with JWT tokens. If your IDP issues opaque tokens instead, you will need to provide a custom implementation.
+
+### Role Mapping
+
+Similarly, Polaris requires additional configuration to map roles provided by Quarkus to roles defined in Polaris. The process happens in two phases: first, Quarkus maps the JWT claims to security roles, using the `quarkus.oidc.roles.*` properties; then, Polaris-specific properties are used to map the Quarkus-provided security roles to Polaris roles:
+
+```properties
+quarkus.oidc.roles.role-claim-path=polaris/roles
+polaris.oidc.principal-roles-mapper.type=default
+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
+```
+
+These mappings can be overridden per OIDC tenant and used across different realms that rely on external identity providers. For example:
+
+```properties
+polaris.oidc.oidc-tenant1.principal-roles-mapper.type=custom
+polaris.oidc.oidc-tenant1.principal-roles-mapper.filter=POLARIS_ROLE:.*
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].regex=POLARIS_ROLE:(.*)
+polaris.oidc.oidc-tenant1.principal-roles-mapper.mappings[0].replacement=POLARIS_ROLE:$1
+```
+
+The default `ActiveRolesProvider` expects the security identity to expose role names in the following format: `POLARIS_ROLE: <role name>`. You can use the `filter` and `mappings` properties to adjust the role names as they appear in the JWT claims.
+
+For example, assume that the security identity produced by Quarkus exposes the following roles: `role_service_admin` and `role_catalog_admin`. Polaris expects `POLARIS_ROLE:service_admin` and `POLARIS_ROLE:catalog_admin` respectively. The following configuration can be used to achieve the desired mapping:
+
+```properties
+# Exclude role names that don't start with "role_"
+polaris.oidc.principal-roles-mapper.filter=role_.*
+# Extract the text after "role_"
+polaris.oidc.principal-roles-mapper.mappings[0].regex=role_(.*)
+# Replace the extracted text with "POLARIS_ROLE:"
+polaris.oidc.principal-roles-mapper.mappings[0].replacement=POLARIS\_ROLE:$1
Review Comment:
Still seeing one backslash here that I think is not necessary.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add External Identity Providers page to unreleased documentation [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on PR #2013:
URL: https://github.com/apache/polaris/pull/2013#issuecomment-3073706955
@adutra FYI I just saw a failure that looks related:
```
hugo_publish_apache-1 | ERROR [en] REF_NOT_FOUND: Ref "realm": "/polaris/site/content/in-dev/unreleased/external-idp.md:107:221": page reference "realm" is ambiguous
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org