From 2dfe0f00f099ffdd735fa94fc15f11d7cb2da3a5 Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Sat, 7 Nov 2026 23:20:01 +0000 Subject: [PATCH] Serve OpenSharing's recipient API and share grants from Unity Catalog The provider API now also creates, reads, changes and deletes recipients, rotates their tokens, and grants shares to them. UC records each recipient's owner in its authorizer, in the same transaction as the recipient itself. Granting a share to a recipient takes owning the share, and owning the recipient or USE RECIPIENT, checked by annotation with the recipient read from the typed body, so a request grants to one recipient at most. Activation links are built on server.opensharing.public-url, which embedded OpenSharing now requires. The sharing docs page covers the new endpoints and privileges. Signed-off-by: Sun Cao Support admin ownership transfers of recipients PATCH /recipients/{recipient} takes a catalog admin transferring the ownership to the body's ownerId, on its own, with UC's owner record moving to the new owner in the same transaction. Co-authored-by: Isaac Document ownership transfers in the sharing docs Co-authored-by: Isaac --- docs/server/opensharing.md | 33 +++- .../sharing/GrantedRecipientExtractor.java | 34 ++++ .../sharing/OpenSharingProviderService.java | 171 ++++++++++++++++- .../sharing/OpenSharingEmbeddedTest.java | 174 ++++++++++++++++-- 4 files changed, 383 insertions(+), 29 deletions(-) create mode 100644 server/src/main/java/io/unitycatalog/server/service/sharing/GrantedRecipientExtractor.java diff --git a/docs/server/opensharing.md b/docs/server/opensharing.md index 87d4cd7437..a3b75d3e15 100644 --- a/docs/server/opensharing.md +++ b/docs/server/opensharing.md @@ -14,14 +14,15 @@ server.opensharing.enabled=true server.opensharing.public-url=https://sharing.example.com ``` -It needs authorization, because each share is owned by the Unity Catalog user who creates it. The -required `server.opensharing.public-url` value is the address recipients reach this server at; -OpenSharing uses it in activation links. The code is part of the server: no extra module or classpath -is needed. +It needs authorization, because each share and recipient is owned by the Unity Catalog user who +creates it. `server.opensharing.public-url` is the address recipients reach the server at, which +their activation links name. The code is part of the server: no extra module or classpath is +needed. ## Provider API -The provider API manages shares. It is OpenSharing's API, hosted by Unity Catalog under the Unity +The provider API manages shares, the recipients they are granted to, and the recipients' tokens. It +is OpenSharing's API, hosted by Unity Catalog under the Unity Catalog base path: ```text @@ -43,8 +44,17 @@ describes it. Like the Iceberg REST catalog, it is not part of the Unity Catalog | `GET /shares/{share}` | Gets a share, and the tables in it with `include_shared_data=true` | `USE SHARE` on the metastore, or owning the share | | `PATCH /shares/{share}` | Adds tables to the share, removes them, and changes its other fields, or transfers its ownership with `ownerId` | Owning the share; a transfer takes the metastore owner | | `DELETE /shares/{share}` | Deletes the share | Owning the share | - -Share names are not case sensitive. +| `GET /shares/{share}/permissions` | Lists the recipients the share is granted to | `USE SHARE` on the metastore, or owning the share | +| `PATCH /shares/{share}/permissions` | Grants the share to a recipient, and revokes it | Owning the share; to grant, also `USE RECIPIENT` on the metastore, or owning the recipient | +| `POST /recipients` | Creates a recipient, owned by the caller | `CREATE RECIPIENT` on the metastore | +| `GET /recipients` | Lists the recipients the caller may read | `USE RECIPIENT` on the metastore, or owning the recipient | +| `GET /recipients/{recipient}` | Gets a recipient | `USE RECIPIENT` on the metastore, or owning the recipient | +| `PATCH /recipients/{recipient}` | Changes a recipient, or transfers its ownership with `ownerId` | Owning the recipient; a transfer takes the metastore owner | +| `DELETE /recipients/{recipient}` | Deletes a recipient and its tokens | Owning the recipient | +| `POST /recipients/{recipient}/rotate-token` | Issues a new token with a new activation link | Owning the recipient | + +A request grants a share to one recipient at most. Revoking takes nothing of the recipient, so the +owner of a share can always cut a recipient off. Share and recipient names are not case sensitive. ## Privileges @@ -52,16 +62,19 @@ Share names are not case sensitive. | --- | --- | --- | | `CREATE SHARE` | Metastore | Creating shares | | `USE SHARE` | Metastore | Listing and reading every share, not only the caller's own | +| `CREATE RECIPIENT` | Metastore | Creating recipients | +| `USE RECIPIENT` | Metastore | Listing and reading every recipient, and granting shares to recipients the caller does not own | -The metastore owner holds both. Grant them like any other privilege, with the permissions API or +The metastore owner holds all of them. Grant them like any other privilege, with the permissions API or `bin/uc permission create`. Putting a table in a share takes the access Unity Catalog asks for before it vends the table's read credentials: `USE CATALOG` on its catalog, `USE SCHEMA` on its schema and `SELECT` on the table, or owning them. Only Delta tables with a storage location can be shared. -An owner can't give a share away, but the metastore owner can transfer it to another user with -`ownerId`. When the owner of a share is deleted, nobody can change or delete it. +An owner can't give a share or recipient away, but the metastore owner can transfer it to another +user with `ownerId`. When the owner of a share or recipient is deleted, nobody can change or delete +it. ## Storage credentials diff --git a/server/src/main/java/io/unitycatalog/server/service/sharing/GrantedRecipientExtractor.java b/server/src/main/java/io/unitycatalog/server/service/sharing/GrantedRecipientExtractor.java new file mode 100644 index 0000000000..ded1dd2850 --- /dev/null +++ b/server/src/main/java/io/unitycatalog/server/service/sharing/GrantedRecipientExtractor.java @@ -0,0 +1,34 @@ +package io.unitycatalog.server.service.sharing; + +import io.opensharing.http.ApiException; +import io.opensharing.share.UpdateSharePermissionsRequest; +import io.unitycatalog.server.auth.decorator.AuthorizeValueExtractor; +import java.util.LinkedHashSet; +import java.util.Set; + +/** + * The recipient a {@code PATCH /shares/{share}/permissions} body grants to, or null for none. A + * resource key names one recipient, so a body that grants to more than one is refused. A change + * that only revokes names none, and OpenSharing rejects an invalid change itself: it checks every + * change before applying any. + */ +public final class GrantedRecipientExtractor implements AuthorizeValueExtractor { + + @Override + public Object extract(Object body) { + Set granted = new LinkedHashSet<>(); + for (UpdateSharePermissionsRequest.Change change : + ((UpdateSharePermissionsRequest) body).changes()) { + if (change != null + && !change.add().isEmpty() + && change.recipientName() != null + && !change.recipientName().isBlank()) { + granted.add(change.recipientName()); + } + } + if (granted.size() > 1) { + throw ApiException.invalidParameter("a request can grant a share to only one recipient"); + } + return granted.isEmpty() ? null : granted.iterator().next(); + } +} diff --git a/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingProviderService.java b/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingProviderService.java index 1957d7414b..d93c10faf6 100644 --- a/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingProviderService.java +++ b/server/src/main/java/io/unitycatalog/server/service/sharing/OpenSharingProviderService.java @@ -1,6 +1,7 @@ package io.unitycatalog.server.service.sharing; import static io.unitycatalog.server.model.SecurableType.METASTORE; +import static io.unitycatalog.server.model.SecurableType.RECIPIENT; import static io.unitycatalog.server.model.SecurableType.SHARE; import com.linecorp.armeria.common.HttpResponse; @@ -17,10 +18,18 @@ import io.opensharing.auth.UserContext; import io.opensharing.http.ApiException; import io.opensharing.http.ListResponse; +import io.opensharing.recipient.CreateRecipientRequest; +import io.opensharing.recipient.IssuedTokenResponse; +import io.opensharing.recipient.RecipientResponse; +import io.opensharing.recipient.RecipientService; +import io.opensharing.recipient.RotateTokenRequest; +import io.opensharing.recipient.UpdateRecipientRequest; import io.opensharing.runtime.OpenSharing; import io.opensharing.share.CreateShareRequest; +import io.opensharing.share.SharePermissionResponse; import io.opensharing.share.ShareResponse; import io.opensharing.share.ShareService; +import io.opensharing.share.UpdateSharePermissionsRequest; import io.opensharing.share.UpdateShareRequest; import io.unitycatalog.server.auth.UnityCatalogAuthorizer; import io.unitycatalog.server.auth.annotation.AuthorizeExpression; @@ -42,11 +51,12 @@ import java.util.UUID; /** - * OpenSharing's provider API for shares, served by Unity Catalog. UC authenticates callers and - * authorizes each method by its expression, for both sharing privileges and ownership, per item for - * listings. Share owners are recorded in UC's authorizer, so expressions can name them. Bodies and - * errors keep OpenSharing's wire format: the server registers this service with OpenSharing's JSON - * mapper and {@link OpenSharingExceptionHandler}. + * OpenSharing's provider API for shares, their recipient grants, and recipients, served by Unity + * Catalog. UC authenticates callers and authorizes each method by its expression, for both sharing + * privileges and ownership: per item for listings, and of the recipient for a grant. Share and + * recipient owners are recorded in UC's authorizer, so expressions can name them. Bodies and errors + * keep OpenSharing's wire format: the server registers this service with OpenSharing's JSON mapper + * and {@link OpenSharingExceptionHandler}. */ @ProducesJson public final class OpenSharingProviderService extends AuthorizedService @@ -54,19 +64,36 @@ public final class OpenSharingProviderService extends AuthorizedService private static final String OWN_SHARE = "#authorize(#principal, #share, OWNER)"; - /** Transferring a share's ownership: the ownerId the body sets, checked by catalog admins. */ - private static final String TRANSFER_SHARE = + /** Transferring a share's or recipient's ownership: the ownerId the body sets, admin only. */ + private static final String TRANSFER = """ #ownerId != null && #authorize(#principal, #metastore, OWNER) """; + private static final String OWN_RECIPIENT = "#authorize(#principal, #recipient, OWNER)"; + private static final String READ_SHARE = """ #authorizeAny(#principal, #metastore, OWNER, USE_SHARE) || #authorize(#principal, #share, OWNER) """; + private static final String READ_RECIPIENT = + """ + #authorizeAny(#principal, #metastore, OWNER, USE_RECIPIENT) || + #authorize(#principal, #recipient, OWNER) + """; + + /** {@code #recipient} is the one recipient a request grants to, or null for none. */ + private static final String GRANT_SHARE = + """ + #authorize(#principal, #share, OWNER) && (#recipient == null || + #authorizeAny(#principal, #metastore, OWNER, USE_RECIPIENT) || + #authorize(#principal, #recipient, OWNER)) + """; + private final ShareService shares; + private final RecipientService recipients; private final MetastoreRepository metastore; private final HibernateTransactions transactions; private final OpenSharingExceptionHandler exceptionHandler = new OpenSharingExceptionHandler(); @@ -79,6 +106,7 @@ public final class OpenSharingProviderService extends AuthorizedService ServerProperties serverProperties) { super(authorizer, repositories, serverProperties); this.shares = openSharing.shares(); + this.recipients = openSharing.recipients(); this.metastore = repositories.getMetastoreRepository(); this.transactions = transactions; } @@ -135,7 +163,7 @@ public ShareResponse getShare( * to the body's {@code ownerId}. */ @Patch("/shares/{share}") - @AuthorizeExpression(OWN_SHARE + " || " + TRANSFER_SHARE) + @AuthorizeExpression(OWN_SHARE + " || " + TRANSFER) @AuthorizeResourceKey(METASTORE) public ShareResponse updateShare( @Param("share") @AuthorizeResourceKey(SHARE) String share, @@ -172,6 +200,133 @@ public HttpResponse deleteShare(@Param("share") @AuthorizeResourceKey(SHARE) Str return HttpResponse.of(HttpStatus.NO_CONTENT); } + /** + * {@code GET /shares/{share}/permissions}: lists which recipients the share is granted to. Owner + * or USE SHARE. + */ + @Get("/shares/{share}/permissions") + @AuthorizeExpression(READ_SHARE) + @AuthorizeResourceKey(METASTORE) + public ListResponse listSharePermissions( + @Param("share") @AuthorizeResourceKey(SHARE) String share, + @Param("maxResults") Optional maxResults, + @Param("pageToken") Optional pageToken) { + return shares.listPermissions(user(), share, maxResults.orElse(null), pageToken.orElse(null)); + } + + /** + * {@code PATCH /shares/{share}/permissions}: grants and revokes recipients. Owner only, and + * granting to a recipient takes what getting it does: owning it, or USE RECIPIENT. A request + * grants to one recipient at most. Revoking takes nothing of the recipient, so an owner can + * always cut one off. + */ + @Patch("/shares/{share}/permissions") + @AuthorizeExpression(GRANT_SHARE) + @AuthorizeResourceKey(METASTORE) + public ListResponse updateSharePermissions( + @Param("share") @AuthorizeResourceKey(SHARE) String share, + @AuthorizeResourceKey(value = RECIPIENT, extractor = GrantedRecipientExtractor.class) + UpdateSharePermissionsRequest request) { + return shares.updatePermissions(user(), share, request); + } + + /** + * {@code POST /recipients}: creates a recipient owned by the caller. The recipient and its owner + * record in UC's authorizer are one unit of work, like a share's. + */ + @Post("/recipients") + @StatusCode(201) + @AuthorizeExpression("#authorizeAny(#principal, #metastore, OWNER, CREATE_RECIPIENT)") + @AuthorizeResourceKey(METASTORE) + public RecipientResponse createRecipient(CreateRecipientRequest request) { + return transactions.inTransaction( + false, + session -> { + RecipientResponse created = recipients.create(user(), request); + initializeBasicAuthorization(created.id()); + return created; + }); + } + + /** + * {@code GET /recipients}: lists every recipient with USE RECIPIENT, otherwise the caller's. + * Filtered per recipient after paging, like {@link #listShares}. + */ + @Get("/recipients") + @AuthorizeExpression(READ_RECIPIENT) + @ResponseAuthorizeFilter + @AuthorizeResourceKey(METASTORE) + public ListResponse listRecipients( + @Param("maxResults") Optional maxResults, + @Param("pageToken") Optional pageToken) { + return visible(RECIPIENT, recipients.listAll(maxResults.orElse(null), pageToken.orElse(null))); + } + + /** {@code GET /recipients/{recipient}}: gets a recipient by name. Owner or USE RECIPIENT. */ + @Get("/recipients/{recipient}") + @AuthorizeExpression(READ_RECIPIENT) + @AuthorizeResourceKey(METASTORE) + public RecipientResponse getRecipient( + @Param("recipient") @AuthorizeResourceKey(RECIPIENT) String recipient) { + return recipients.get(user(), recipient); + } + + /** + * {@code PATCH /recipients/{recipient}}: updates the fields set in the body. Owner only; a + * catalog admin may instead transfer the ownership to the body's {@code ownerId}. + */ + @Patch("/recipients/{recipient}") + @AuthorizeExpression(OWN_RECIPIENT + " || " + TRANSFER) + @AuthorizeResourceKey(METASTORE) + public RecipientResponse updateRecipient( + @Param("recipient") @AuthorizeResourceKey(RECIPIENT) String recipient, + @AuthorizeKey(key = "ownerId") UpdateRecipientRequest request) { + return transactions.inTransaction( + false, + session -> { + if (request.ownerId() == null) { + return recipients.update(user(), recipient, request); + } + // Read before the update, which moves the owner in OpenSharing. + String ownerBefore = recipients.get(user(), recipient).ownerId(); + RecipientResponse updated = recipients.update(user(), recipient, request); + transferOwnership(updated.id(), ownerBefore, request.ownerId()); + return updated; + }); + } + + /** + * {@code DELETE /recipients/{recipient}}: deletes the recipient, its tokens and its owner record + * in UC's authorizer as one unit of work. Owner only. + */ + @Delete("/recipients/{recipient}") + @AuthorizeExpression(OWN_RECIPIENT) + public HttpResponse deleteRecipient( + @Param("recipient") @AuthorizeResourceKey(RECIPIENT) String recipient) { + UUID id = id(RECIPIENT, recipient); + transactions.inTransaction( + false, + session -> { + recipients.delete(user(), recipient); + removeAuthorizations(id.toString()); + return null; + }); + return HttpResponse.of(HttpStatus.NO_CONTENT); + } + + /** + * {@code POST /recipients/{recipient}/rotate-token}: issues a replacement token with a new + * activation link. Owner only. + */ + @Post("/recipients/{recipient}/rotate-token") + @StatusCode(201) + @AuthorizeExpression(OWN_RECIPIENT) + public IssuedTokenResponse rotateRecipientToken( + @Param("recipient") @AuthorizeResourceKey(RECIPIENT) String recipient, + RotateTokenRequest request) { + return recipients.rotateToken(user(), recipient, request); + } + @Override public ExceptionHandlerFunction exceptionHandler() { return exceptionHandler; 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 311ef923ec..90792f5b61 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 @@ -2,6 +2,7 @@ import static java.nio.charset.StandardCharsets.UTF_8; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; import static org.assertj.core.api.Assertions.fail; import com.fasterxml.jackson.databind.JsonNode; @@ -14,19 +15,25 @@ import com.linecorp.armeria.common.MediaType; import com.linecorp.armeria.common.RequestHeaders; import com.linecorp.armeria.common.RequestHeadersBuilder; +import io.unitycatalog.server.UnityCatalogServer; import io.unitycatalog.server.base.auth.BaseAuthCRUDTest; +import io.unitycatalog.server.utils.ServerProperties; import io.unitycatalog.server.utils.ServerProperties.Property; import java.io.IOException; import java.net.URLEncoder; import java.time.Duration; import java.util.ArrayList; +import java.util.Arrays; import java.util.List; +import java.util.Properties; +import java.util.stream.Collectors; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; /** Embedded OpenSharing on a UC server with authorization on, driven over HTTP. */ 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 ALICE = "alice@example.com"; @@ -34,6 +41,7 @@ public class OpenSharingEmbeddedTest extends BaseAuthCRUDTest { "{\"updates\": [{\"action\": \"ADD\", \"dataObject\": {\"name\": \"main.sales.orders\"," + " \"type\": \"TABLE\", \"sharedAs\": \"sales.orders\"}}]}"; private static final String COMMENT = "{\"comment\": \"x\"}"; + private static final String ROTATE_TOKEN = "{\"tokenExpirationDays\": 1}"; private static final ObjectMapper JSON = new ObjectMapper(); private WebClient client; @@ -44,8 +52,7 @@ public class OpenSharingEmbeddedTest extends BaseAuthCRUDTest { protected void setUpProperties() { super.setUpProperties(); serverProperties.setProperty(Property.OPENSHARING_ENABLED.getKey(), "true"); - serverProperties.setProperty( - Property.OPENSHARING_PUBLIC_URL.getKey(), "https://sharing.example.com"); + serverProperties.setProperty(Property.OPENSHARING_PUBLIC_URL.getKey(), PUBLIC_URL + "/"); } @BeforeEach @@ -95,10 +102,16 @@ public void providerApiRequiresUnityCatalogPrivileges() { // Alice can't create a share without CREATE SHARE. expect(403, alice, HttpMethod.POST, PROVIDER + "/shares", share("alice_share")); - // CREATE SHARE on the metastore lets alice create a share. + // Alice can't create a recipient without CREATE RECIPIENT. + expect(403, alice, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); + // Alice gets CREATE SHARE on the metastore. grant("metastore", "metastore", "CREATE SHARE"); + // Alice gets CREATE RECIPIENT on the metastore. + grant("metastore", "metastore", "CREATE RECIPIENT"); // Alice creates her share. expect(201, alice, HttpMethod.POST, PROVIDER + "/shares", share("alice_share")); + // Alice creates her recipient. + expect(201, alice, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); // Sharing a table takes the access UC asks for before vending its read credentials. expect(403, alice, HttpMethod.PATCH, PROVIDER + "/shares/alice_share", ADD_ORDERS); @@ -113,59 +126,139 @@ public void providerApiRequiresUnityCatalogPrivileges() { // Alice adds the table to her share. expect(200, alice, HttpMethod.PATCH, PROVIDER + "/shares/alice_share", ADD_ORDERS); - // Other users' shares take USE SHARE to read. + // Other users' shares and recipients take USE SHARE and USE RECIPIENT to read, and granting a + // share to another user's recipient takes USE RECIPIENT. A request grants to one recipient, so + // one granting to two is refused before either is granted. Revoking takes nothing of the + // recipient, so it reaches OpenSharing, which finds no grant. + String alicePermissions = PROVIDER + "/shares/alice_share/permissions"; // Admin creates a share that alice doesn't own. expect(201, admin, HttpMethod.POST, PROVIDER + "/shares", share("admin_share")); + // Admin creates a recipient that alice doesn't own. + expect(201, admin, HttpMethod.POST, PROVIDER + "/recipients", recipient("globex")); // Without USE SHARE, alice lists only her own share. assertThat(names(expect(200, alice, HttpMethod.GET, PROVIDER + "/shares", null))) .containsExactly("alice_share"); // Without USE SHARE, alice can't read admin's share. expectDenied(alice, HttpMethod.GET, PROVIDER + "/shares/admin_share", null); - // USE SHARE lets alice list and read admin's share. + // Without USE SHARE, alice can't list who admin's share is granted to. + expectDenied(alice, HttpMethod.GET, PROVIDER + "/shares/admin_share/permissions", null); + // Without USE RECIPIENT, alice can't read admin's recipient. + expectDenied(alice, HttpMethod.GET, PROVIDER + "/recipients/globex", null); + // Without USE RECIPIENT, alice can't grant her share to admin's recipient. + expectDenied(alice, HttpMethod.PATCH, alicePermissions, shareWith("globex")); + // A request that grants to two recipients is refused before either is granted. + assertThat( + expect(400, alice, HttpMethod.PATCH, alicePermissions, shareWith("acme", "globex")) + .path("message") + .asText()) + .contains("only one recipient"); + // The refused request granted nothing. + assertThat(expect(200, alice, HttpMethod.GET, alicePermissions, null).path("items")).isEmpty(); + // Alice can grant her share to her own recipient. + expect(200, alice, HttpMethod.PATCH, alicePermissions, shareWith("acme")); + // Revoking a grant that doesn't exist reaches OpenSharing, which answers 404. + expect(404, alice, HttpMethod.PATCH, alicePermissions, unshareWith("globex")); + // Alice gets USE SHARE on the metastore. grant("metastore", "metastore", "USE SHARE"); + // Alice gets USE RECIPIENT on the metastore. + grant("metastore", "metastore", "USE RECIPIENT"); // Alice now lists both shares. assertThat(names(expect(200, alice, HttpMethod.GET, PROVIDER + "/shares", null))) .containsExactlyInAnyOrder("alice_share", "admin_share"); // Alice can now read admin's share. expect(200, alice, HttpMethod.GET, PROVIDER + "/shares/admin_share", null); + // Alice can now see who admin's share is granted to. + expect(200, alice, HttpMethod.GET, PROVIDER + "/shares/admin_share/permissions", null); + // Alice can now read admin's recipient. + expect(200, alice, HttpMethod.GET, PROVIDER + "/recipients/globex", null); + // USE RECIPIENT lets alice grant her share to admin's recipient. + expect(200, alice, HttpMethod.PATCH, alicePermissions, shareWith("globex")); - // It doesn't let alice change one: that takes ownership, which UC checks first. + // Neither lets alice change them: that takes ownership, which UC checks first. String adminShare = PROVIDER + "/shares/admin_share"; + String globex = PROVIDER + "/recipients/globex"; // Alice can't update admin's share even with USE SHARE. expectDenied(alice, HttpMethod.PATCH, adminShare, COMMENT); + // Alice can't grant admin's share. + expectDenied(alice, HttpMethod.PATCH, adminShare + "/permissions", shareWith("acme")); + // Alice can't revoke admin's share either. + expectDenied(alice, HttpMethod.PATCH, adminShare + "/permissions", unshareWith("acme")); // Alice can't delete admin's share even with USE SHARE. expectDenied(alice, HttpMethod.DELETE, adminShare, null); + // Alice can't change admin's recipient even with USE RECIPIENT. + expectDenied(alice, HttpMethod.PATCH, globex, COMMENT); + // Alice can't rotate the recipient's token. + expectDenied(alice, HttpMethod.POST, globex + "/rotate-token", ROTATE_TOKEN); + // Alice can't delete the recipient. + expectDenied(alice, HttpMethod.DELETE, globex, null); } @Test - public void unityCatalogRecordsShareOwners() { - // CREATE SHARE on the metastore lets alice create a share. + public void startupNamesWhatEmbeddedOpenSharingNeeds() { + // The server's properties, without the public URL. + Properties withoutPublicUrl = new Properties(); + withoutPublicUrl.putAll(serverProperties); + withoutPublicUrl.remove(Property.OPENSHARING_PUBLIC_URL.getKey()); + // Building the server fails, and the error names the missing setting. + assertThatThrownBy( + () -> + UnityCatalogServer.builder() + .serverProperties(new ServerProperties(withoutPublicUrl)) + .hibernateConfigurator(hibernateConfigurator) + .build()) + .isInstanceOf(IllegalStateException.class) + .hasMessageContaining(Property.OPENSHARING_PUBLIC_URL.getKey()); + } + + @Test + public void unityCatalogRecordsShareAndRecipientOwners() { + // Alice gets CREATE SHARE on the metastore. grant("metastore", "metastore", "CREATE SHARE"); + // Alice gets CREATE RECIPIENT on the metastore. + grant("metastore", "metastore", "CREATE RECIPIENT"); // Alice creates her share. expect(201, alice, HttpMethod.POST, PROVIDER + "/shares", share("alice_share")); + // Alice creates her recipient. + expect(201, alice, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); // Reading one takes ownership, which UC records as OpenSharing creates it, or what the // metastore owner holds. Names resolve in any case, as OpenSharing's do. for (String token : List.of(alice, admin)) { // The owner and the metastore owner read the share by a differently cased name. expect(200, token, HttpMethod.GET, PROVIDER + "/shares/Alice_Share", null); + // Both can read alice's recipient too. + expect(200, token, HttpMethod.GET, PROVIDER + "/recipients/acme", null); } // An unknown share name is OpenSharing's 404. JsonNode missing = expect(404, alice, HttpMethod.GET, PROVIDER + "/shares/nope", null); assertThat(missing.path("errorCode").asText()).isEqualTo("RESOURCE_DOES_NOT_EXIST"); + // So is an unknown recipient name. + expect(404, alice, HttpMethod.GET, PROVIDER + "/recipients/nope", null); // Changing one takes ownership alone. expect(200, alice, HttpMethod.PATCH, PROVIDER + "/shares/alice_share", COMMENT); + // Alice can change her recipient. + expect(200, alice, HttpMethod.PATCH, PROVIDER + "/recipients/acme", COMMENT); + // Alice can rotate her recipient's token. + expect(201, alice, HttpMethod.POST, PROVIDER + "/recipients/acme/rotate-token", ROTATE_TOKEN); // Admin, who doesn't own the share, can't change it. expectDenied(admin, HttpMethod.PATCH, PROVIDER + "/shares/alice_share", COMMENT); + // Nor can admin delete alice's recipient. + expectDenied(admin, HttpMethod.DELETE, PROVIDER + "/recipients/acme", null); - // Ownership is recorded by id, so a share made again under the same name is its new - // creator's alone. + // Ownership is recorded by id, so a share or recipient made again under the same name is + // its new creator's alone. expect(204, alice, HttpMethod.DELETE, PROVIDER + "/shares/alice_share", null); - // Admin recreates a share under the name alice's old share had. + // Alice deletes her recipient. + expect(204, alice, HttpMethod.DELETE, PROVIDER + "/recipients/acme", null); + // Admin recreates a share under alice's old share's name. expect(201, admin, HttpMethod.POST, PROVIDER + "/shares", share("alice_share")); + // Admin recreates a recipient under alice's old recipient's name. + expect(201, admin, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); // Alice can't read the recreated share. expectDenied(alice, HttpMethod.GET, PROVIDER + "/shares/alice_share", null); + // Alice can't read the recreated recipient. + expectDenied(alice, HttpMethod.GET, PROVIDER + "/recipients/acme", null); // Alice can't delete the recreated share. expectDenied(alice, HttpMethod.DELETE, PROVIDER + "/shares/alice_share", null); } @@ -204,16 +297,49 @@ public void adminTransfersASharesOwnership() throws IOException { expectDenied(alice, HttpMethod.PATCH, path, COMMENT); } + @Test + public void adminTransfersARecipientsOwnership() throws IOException { + // CREATE RECIPIENT on the metastore lets alice create a recipient. + grant("metastore", "metastore", "CREATE RECIPIENT"); + // Alice creates her recipient. + expect(201, alice, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); + String bob = createEnabledUserReturningId("bob@example.com"); + String bobToken = securityContext.createAccessToken("bob@example.com", Duration.ofHours(1)); + String transfer = "{\"ownerId\": \"" + bob + "\"}"; + String path = PROVIDER + "/recipients/acme"; + + // A transfer takes a catalog admin, and rides on no other change. Alice owns the recipient, + // so UC lets her PATCH it and OpenSharing's own admin check denies the transfer. + assertThat(expect(403, alice, HttpMethod.PATCH, path, transfer).path("message").asText()) + .isEqualTo("only an admin of the catalog may change the owner of recipient 'acme'"); + // A catalog admin can transfer the recipient's owner. + JsonNode transferred = expect(200, admin, HttpMethod.PATCH, path, transfer); + assertThat(transferred.path("ownerId").asText()).isEqualTo(bob); + + // UC's owner record moved with it: the new owner keeps the recipient, the old one loses it. + expect(200, bobToken, HttpMethod.PATCH, path, COMMENT); + // The new owner can rotate the recipient's token. + expect(201, bobToken, HttpMethod.POST, path + "/rotate-token", ROTATE_TOKEN); + // The previous owner can no longer change the recipient. + expectDenied(alice, HttpMethod.PATCH, path, COMMENT); + } + @Test public void listingsAreFilteredPerItemAfterPaging() { // CREATE SHARE on the metastore lets alice create shares. grant("metastore", "metastore", "CREATE SHARE"); + // CREATE RECIPIENT on the metastore lets alice create recipients. + grant("metastore", "metastore", "CREATE RECIPIENT"); // Admin's first share, which alice can't see. expect(201, admin, HttpMethod.POST, PROVIDER + "/shares", share("a_share")); // Admin's second share, which alice can't see. expect(201, admin, HttpMethod.POST, PROVIDER + "/shares", share("b_share")); // Alice's own share, the only one she can see. expect(201, alice, HttpMethod.POST, PROVIDER + "/shares", share("c_share")); + // Admin's recipient, which alice can't see. + expect(201, admin, HttpMethod.POST, PROVIDER + "/recipients", recipient("globex")); + // Alice's own recipient, the only one she can see. + expect(201, alice, HttpMethod.POST, PROVIDER + "/recipients", recipient("acme")); // As in UC's own listings, a page is filtered after it is read, so alice's only share comes // on the last of three one-share pages. @@ -229,6 +355,13 @@ public void listingsAreFilteredPerItemAfterPaging() { } while (token != null); // Alice's only share comes on the last of three pages. assertThat(pages).containsExactly(List.of(), List.of(), List.of("c_share")); + + // Recipients carry their activation links, so other users' must be dropped too. + assertThat(names(expect(200, alice, HttpMethod.GET, PROVIDER + "/recipients", null))) + .containsExactly("acme"); + // The metastore owner sees every recipient. + assertThat(names(expect(200, admin, HttpMethod.GET, PROVIDER + "/recipients", null))) + .containsExactly("acme", "globex"); } private static String share(String name) { @@ -258,6 +391,25 @@ private String createEnabledUserReturningId(String email) throws IOException { return JSON.readTree(response.contentUtf8()).path("id").asText(); } + /** A share permissions change that grants SELECT to each of {@code recipients}. */ + private static String shareWith(String... recipients) { + return Arrays.stream(recipients) + .map("{\"recipientName\": \"%s\", \"add\": [\"SELECT\"]}"::formatted) + .collect(Collectors.joining(", ", "{\"changes\": [", "]}")); + } + + /** A share permissions change that revokes SELECT from {@code recipient}. */ + private static String unshareWith(String recipient) { + return "{\"changes\": [{\"recipientName\": \"%s\", \"remove\": [\"SELECT\"]}]}" + .formatted(recipient); + } + + private static String recipient(String name) { + return "{\"name\": \"" + + name + + "\", \"authenticationType\": \"TOKEN\", \"tokenExpirationDays\": 1}"; + } + private void grant(String securableType, String fullName, String privilege) { permissions(securableType, fullName, "add", privilege); }