diff --git a/docs/server/opensharing.md b/docs/server/opensharing.md index a3b75d3e15..69c54e47c0 100644 --- a/docs/server/opensharing.md +++ b/docs/server/opensharing.md @@ -76,6 +76,24 @@ An owner can't give a share or recipient away, but the metastore owner can trans user with `ownerId`. When the owner of a share or recipient is deleted, nobody can change or delete it. +## Recipients + +Recipients don't use Unity Catalog tokens. Creating a recipient, or rotating its token, returns an +`activationUrl` on `server.opensharing.public-url`. The recipient opens it once, at +`/api/1.0/opensharing/activations/{code}`, and gets a profile file with the endpoint and a bearer +token. Then it reads the shares granted to it over the Delta Sharing protocol, served under: + +```text +/api/1.0/opensharing +``` + +These routes sit outside Unity Catalog's authentication and authorization, on the same port: +OpenSharing authenticates recipients by their own tokens, and Unity Catalog's tokens are not +accepted there. + +A shared table is read with the access of the user who owns its share. When that user loses +`SELECT` on the table, or is deleted or disabled, recipients no longer see the table. + ## Storage credentials OpenSharing reads shared tables through Unity Catalog's credential vendor, so the cloud storage a diff --git a/server/src/main/java/io/unitycatalog/server/ArmeriaServerBuilder.java b/server/src/main/java/io/unitycatalog/server/ArmeriaServerBuilder.java index 9c8c9a1b36..58d69f4280 100644 --- a/server/src/main/java/io/unitycatalog/server/ArmeriaServerBuilder.java +++ b/server/src/main/java/io/unitycatalog/server/ArmeriaServerBuilder.java @@ -49,6 +49,7 @@ import java.lang.reflect.ParameterizedType; import java.util.List; import java.util.Objects; +import java.util.function.Consumer; /** * Wraps Armeria's {@link ServerBuilder} with Unity-Catalog-aware registration. Callers register @@ -209,6 +210,17 @@ ArmeriaServerBuilder annotate(String relativePath, OpenSharingProviderService se return this; } + /** + * Registers routes that authenticate their own callers, such as embedded OpenSharing's + * recipient-facing API, on the API port. They must lie outside the base and control paths, where + * the security decorators would reject their callers' credentials, and bring their own body + * converters and error rendering. + */ + ArmeriaServerBuilder selfAuthenticated(Consumer registration) { + registration.accept(apiVirtualHost); + return this; + } + /** * Wires the access and authentication decorators onto the API path prefixes. The caller owns the * decision of whether to enable authorization (and simply skips calling this when it is diff --git a/server/src/main/java/io/unitycatalog/server/UnityCatalogServer.java b/server/src/main/java/io/unitycatalog/server/UnityCatalogServer.java index 0bee466e41..94216bcd35 100644 --- a/server/src/main/java/io/unitycatalog/server/UnityCatalogServer.java +++ b/server/src/main/java/io/unitycatalog/server/UnityCatalogServer.java @@ -509,6 +509,7 @@ private void addOpenSharingApiServices( OpenSharingLifecycle openSharing = OpenSharingLifecycle.start(serverProperties, repositories, authorizer); armeriaServerBuilder.annotate("opensharing/provider", openSharing.providerService()); + armeriaServerBuilder.selfAuthenticated(openSharing::mountRecipientApi); } private void addSecurityDecorators( diff --git a/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingLifecycle.java b/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingLifecycle.java index a8e423579a..a4c950be02 100644 --- a/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingLifecycle.java +++ b/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingLifecycle.java @@ -1,5 +1,7 @@ package io.unitycatalog.server.service.sharing; +import com.linecorp.armeria.server.VirtualHostBuilder; +import io.opensharing.protocol.OpenSharingRecipientApi; import io.opensharing.runtime.OpenSharing; import io.unitycatalog.server.auth.UnityCatalogAuthorizer; import io.unitycatalog.server.persist.Repositories; @@ -8,7 +10,8 @@ /** * Builds embedded OpenSharing inside Unity Catalog OSS. {@code UnityCatalogServer} registers what - * it builds with the server: the provider API behind UC's security decorators. + * it builds with the server: the provider API behind UC's security decorators, and the + * recipient-facing API, which authenticates recipients by their own tokens, outside them. * *

OpenSharing's tables, all prefixed {@code os_}, are mapped by UC's own session factory, so * OpenSharing and UC share one connection pool and an operation that touches both sides' tables is @@ -16,14 +19,18 @@ */ public final class OpenSharingLifecycle { + private final OpenSharing openSharing; private final OpenSharingProviderService providerService; - private OpenSharingLifecycle(OpenSharingProviderService providerService) { + private OpenSharingLifecycle( + OpenSharing openSharing, OpenSharingProviderService providerService) { + this.openSharing = openSharing; this.providerService = providerService; } /** - * Builds embedded OpenSharing on UC's database and authorizer. + * Builds embedded OpenSharing on UC's database and authorizer. It keeps OpenSharing's default + * protocol and activation paths, the standalone server's, so recipients see one layout. * * @throws IllegalStateException when the server cannot host it as configured */ @@ -52,6 +59,7 @@ public static OpenSharingLifecycle start( .transactions(transactions) .build(); return new OpenSharingLifecycle( + openSharing, new OpenSharingProviderService( openSharing, transactions, authorizer, repositories, serverProperties)); } @@ -60,4 +68,12 @@ public static OpenSharingLifecycle start( public OpenSharingProviderService providerService() { return providerService; } + + /** + * Mounts the sharing protocol and recipient activation on {@code host}, the virtual host that + * serves UC's API. They bring their own JSON converters and error handling. + */ + public void mountRecipientApi(VirtualHostBuilder host) { + OpenSharingRecipientApi.mount(host, openSharing); + } } diff --git a/server/src/main/java/io/unitycatalog/server/utils/ServerProperties.java b/server/src/main/java/io/unitycatalog/server/utils/ServerProperties.java index 5dcb4ea575..2ec8d3f4c5 100644 --- a/server/src/main/java/io/unitycatalog/server/utils/ServerProperties.java +++ b/server/src/main/java/io/unitycatalog/server/utils/ServerProperties.java @@ -368,6 +368,7 @@ public enum Property { S3CompatibleStaticKeyVending.STATIC_KEY.value())), INCLUDE_STACK_TRACE_IN_ERROR("server.include-stacktrace-in-error", "false", BOOLEAN_VALIDATOR), OPENSHARING_ENABLED("server.opensharing.enabled", "false", BOOLEAN_VALIDATOR), + // The address recipients reach this server at; their activation links and profiles name it. OPENSHARING_PUBLIC_URL("server.opensharing.public-url", URL_VALIDATOR); // The is not an exhaustive list. Some property keys like s3.bucketPath.0 with a numbering // suffix is not included. They are only accessed internally from functions like diff --git a/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingDisabledTest.java b/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingDisabledTest.java index dd0b8dce24..61e29650cd 100644 --- a/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingDisabledTest.java +++ b/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingDisabledTest.java @@ -22,6 +22,7 @@ public class OpenSharingDisabledTest extends BaseAuthCRUDTest { @Test public void servesNoSharingRoutes() { + assertThat(get("/api/1.0/opensharing/shares").status().code()).isEqualTo(404); // UC answers any path under its API prefix that no service serves the same way. AggregatedHttpResponse unrouted = get("/api/2.1/unity-catalog/no-such-service"); assertThat(unrouted.status().isSuccess()).isFalse(); diff --git a/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingEmbeddedTest.java b/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingEmbeddedTest.java index 90792f5b61..ddf89102b9 100644 --- a/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingEmbeddedTest.java +++ b/server/src/test/java/io/unitycatalog/server/service/sharing/OpenSharingEmbeddedTest.java @@ -20,6 +20,7 @@ import io.unitycatalog.server.utils.ServerProperties; import io.unitycatalog.server.utils.ServerProperties.Property; import java.io.IOException; +import java.net.URI; import java.net.URLEncoder; import java.time.Duration; import java.util.ArrayList; @@ -30,12 +31,18 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; -/** Embedded OpenSharing on a UC server with authorization on, driven over HTTP. */ +/** + * Embedded OpenSharing on a UC server with authorization on, driven over HTTP. Reading table data + * takes cloud storage, which OpenSharing vends credentials for, so these cover the API down to + * resolving the shared table. + */ public class OpenSharingEmbeddedTest extends BaseAuthCRUDTest { private static final String PUBLIC_URL = "https://sharing.example.com"; private static final String UC = "/api/2.1/unity-catalog"; private static final String PROVIDER = UC + "/opensharing/provider"; + private static final String PROTOCOL = "/api/1.0/opensharing"; + private static final String CONTROL = "/api/1.0/unity-control"; private static final String ALICE = "alice@example.com"; private static final String ADD_ORDERS = "{\"updates\": [{\"action\": \"ADD\", \"dataObject\": {\"name\": \"main.sales.orders\"," @@ -364,6 +371,82 @@ public void listingsAreFilteredPerItemAfterPaging() { .containsExactly("acme", "globex"); } + @Test + public void recipientSeesSharedTableWhileShareOwnerCanReadIt() { + // Alice shares main.sales.orders with her recipient acme. + JsonNode acme = aliceSharesOrdersWithAcme(); + + // Recipients are pointed at the public url, and activate once. + String activationUrl = acme.path("activationUrl").asText(); + assertThat(activationUrl).startsWith(PUBLIC_URL + PROTOCOL + "/activations/"); + String activation = URI.create(activationUrl).getPath(); + // Activation gives a profile file whose endpoint is the public URL's protocol path. + JsonNode profile = expect(200, null, HttpMethod.GET, activation, null); + assertThat(profile.path("endpoint").asText()).isEqualTo(PUBLIC_URL + PROTOCOL); + // An activation link works only once. + expect(404, null, HttpMethod.GET, activation, null); + String token = profile.path("bearerToken").asText(); + + String tables = PROTOCOL + "/shares/sales/schemas/sales/tables"; + // With the profile's token, the recipient lists the share. + assertThat(names(expect(200, token, HttpMethod.GET, PROTOCOL + "/shares", null))) + .containsExactly("sales"); + // It lists the share's table. + assertThat(names(expect(200, token, HttpMethod.GET, tables, null))).containsExactly("orders"); + // It reads the table's metadata, a Delta table. + assertThat(expect(200, token, HttpMethod.GET, tables + "/orders", null).path("format").asText()) + .isEqualTo("delta"); + + // Recipient tokens are OpenSharing's: UC does not take them, and the protocol needs one. + expect(401, token, HttpMethod.GET, UC + "/catalogs", null); + // The protocol refuses a request without a token. + JsonNode anonymous = expect(401, null, HttpMethod.GET, PROTOCOL + "/shares", null); + assertThat(anonymous.path("errorCode").asText()).isEqualTo("UNAUTHENTICATED"); + // The protocol refuses a UC access token too. + expect(401, alice, HttpMethod.GET, PROTOCOL + "/shares", null); + + // The table is resolved with the share owner's access, so a recipient loses it with them. To + // the recipient it is gone, as if dropped. + revoke("table", "main.sales.orders", "SELECT"); + // The recipient then gets a 404 for the table. + expect(404, token, HttpMethod.GET, tables + "/orders", null); + } + + @Test + public void recipientLosesSharedTableOnceShareOwnerIsDeleted() { + // Alice shares main.sales.orders with her recipient acme. + JsonNode acme = aliceSharesOrdersWithAcme(); + String activation = URI.create(acme.path("activationUrl").asText()).getPath(); + // Acme activates its link and keeps the profile's token. + String token = expect(200, null, HttpMethod.GET, activation, null).path("bearerToken").asText(); + String orders = PROTOCOL + "/shares/sales/schemas/sales/tables/orders"; + // The recipient can read the table while alice can. + expect(200, token, HttpMethod.GET, orders, null); + + // UC keeps a deleted user, disabled, and a disabled owner can't read the table either. + String aliceId = + expect(200, alice, HttpMethod.GET, CONTROL + "/scim2/Me", null).path("id").asText(); + // Admin deletes alice. + expect(200, admin, HttpMethod.DELETE, CONTROL + "/scim2/Users/" + aliceId, null); + // The recipient then gets a 404 for the table. + expect(404, token, HttpMethod.GET, orders, null); + } + + /** Alice, given the privileges to, shares main.sales.orders as sales.orders with acme. */ + private JsonNode aliceSharesOrdersWithAcme() { + grant("metastore", "metastore", "CREATE SHARE"); + grant("metastore", "metastore", "CREATE RECIPIENT"); + grant("catalog", "main", "USE CATALOG"); + grant("schema", "main.sales", "USE SCHEMA"); + grant("table", "main.sales.orders", "SELECT"); + expect(201, alice, HttpMethod.POST, PROVIDER + "/shares", share("sales")); + expect(200, alice, HttpMethod.PATCH, PROVIDER + "/shares/sales", ADD_ORDERS); + JsonNode acme = + expect(201, alice, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); + expect(200, alice, HttpMethod.PATCH, PROVIDER + "/shares/sales/permissions", shareWith("acme")); + return acme; + } + private static String share(String name) { return "{\"name\": \"" + name + "\"}"; } @@ -414,6 +497,10 @@ private void grant(String securableType, String fullName, String privilege) { permissions(securableType, fullName, "add", privilege); } + private void revoke(String securableType, String fullName, String privilege) { + permissions(securableType, fullName, "remove", privilege); + } + private void permissions(String securableType, String fullName, String change, String privilege) { expect( 200,