Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/server/opensharing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<VirtualHostBuilder> 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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -8,22 +10,27 @@

/**
* 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.
*
* <p>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
* one transaction.
*/
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
*/
Expand Down Expand Up @@ -52,6 +59,7 @@ public static OpenSharingLifecycle start(
.transactions(transactions)
.build();
return new OpenSharingLifecycle(
openSharing,
new OpenSharingProviderService(
openSharing, transactions, authorizer, repositories, serverProperties));
}
Expand All @@ -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);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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\","
Expand Down Expand Up @@ -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 + "\"}";
}
Expand Down Expand Up @@ -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,
Expand Down