eric-maynard commented on code in PR #1478: URL: https://github.com/apache/polaris/pull/1478#discussion_r2064161954
########## site/content/in-dev/unreleased/realm.md: ########## @@ -0,0 +1,57 @@ +--- +# +# 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: Entities +type: docs +weight: 400 +--- + +This page explains what a realm is and what it is used for in Polaris. + +### What is it? + +A realm in software systems often refers to a security or authentication domain. It represents a boundary within which security policies and isolation mechanisms are applied and enforced. <br/> +In the context of applications, a realm could define a scope for managing user identities, authentication, and authorization. <br/> +To be more specific, a realm in Polaris represents an isolated "universe" within the system, such as different deployments, environments, regions or distinct accounts. <br/> +Realms serve as a way to partition and manage data and services, ensuring that operations are performed within the correct logical context. <br/> +Every REST request has a realm associated with it. If not specified the default realm is used (POLARIS). Refer to [Configuration]({{% ref "configuration" %}}) for more details. + +### What problem does it solve? + +**Security Management:** By defining a realm, systems can manage authentication and authorization in a modular and organized way. It allows for the separation of security concerns and the application of policies specific to different areas of an application. <br/> + +**Scalability:** Realms help manage users and roles across different services or modules, providing flexibility and scalability. <br/> + +**Isolation:** Realms can isolate different parts of a system, ensuring that security breaches or policies in one realm do not affect others. + +### How is it used in the system? + +**Authentication and Authorization:** For example, in `BasePolarisAuthenticator`, `RealmContext` is used to provide context about the current security domain, which can be crucial for authenticating users or services. <br/> + +**Configuration:** Realms are configured to specify which users or services are allowed to access resources or perform certain actions. <br/> + +**Isolation:** In methods like `createEntityManagerFactory(@Nonnull RealmContext realmContext)` from `PolarisEclipseLinkPersistenceUnit` interface, the realm context influence how resources are created or managed based on the security policies of that realm. <br/> +An example of this is the way a realm name is used to create a database connection url so that you have one database instance per realm. Review Comment: I think for Polaris admins this is the most salient point -- "realm" as a concept is essentially one layer above "catalog", which itself is used to segregate different Iceberg Catalogs from one another. -- 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-unsubscr...@polaris.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
