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
33 changes: 23 additions & 10 deletions docs/server/opensharing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -43,25 +44,37 @@ 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

| Privilege | On | Allows |
| --- | --- | --- |
| `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

Expand Down
Original file line number Diff line number Diff line change
@@ -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<String> 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();
}
}
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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;
Expand All @@ -42,31 +51,49 @@
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
implements RegisteredService {

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();
Expand All @@ -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;
}
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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<SharePermissionResponse> listSharePermissions(
@Param("share") @AuthorizeResourceKey(SHARE) String share,
@Param("maxResults") Optional<Integer> maxResults,
@Param("pageToken") Optional<String> 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<SharePermissionResponse> 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<RecipientResponse> listRecipients(
@Param("maxResults") Optional<Integer> maxResults,
@Param("pageToken") Optional<String> 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;
Expand Down
Loading