Ledger API service permission and scope of admin token

Questions
,
#1

Hi, Just wondering things like ledger time service and ledger identity service, does the user need admin=true token to use it or it is open to everyone? Is it ledger specific implementation?

For the admin token in a distributed scenario, does it mean that a participant can make changes or configurations that affect the whole ledger if s/he obtains the admin token?

2 Likes
#2

The ledger identity service only requires public claims so it needs a valid token but no specific actAs, readAs or admin claims. The time service requires public claims for GetTime and admin claims for SetTime. Note that the time service is only available in static time mode on sandbox and is intended for testing not for production ledgers so you usually use it without authentication.

You can find a table with all ledger API endpoints and the required claims at https://docs.daml.com/app-dev/authorization.html#access-tokens-and-claims.

As for your question about the admin token, I think it helps to take a look at what you can do with such a token:

  1. Interact with the time service. As mentioned above, this is only intended for testing. I’m not aware of a distributed ledger that actually supports this.
  2. Interact with the reset service. Again only intended for testing, I don’t know a distributed ledger that supports this.
  3. Allocate parties. This is a production feature but you allocate the party on the given participant so it’s in some sense “local” and if the participant prefixes all party ids by an identifier for the participant you don’t have to worry about collisions across participants.
  4. Upload packages. This is a production feature and those packages are distributed to other participants. However, it is fairly harmless because packages are content-addressed and you cannot delete them.

So an admin token allows you to allocate new parties and upload packages but both of those are purely additive.

2 Likes
#3

There is another service that requires admin claims: the config management service, in particular the SetTimeModel call. This call sets ledger-wide configuration parameters.

It is expected that ledgers take additional measures to make sure only ledger operators can use this endpoint, for example, by only accepting the time model change from a designated trusted participant. Ledgers can also choose to not implement this method.

3 Likes
#4

@cocreature, @Robert_Autenrieth. Thanks for the answer. Just went through the table on page https://docs.daml.com/app-dev/authorization.html?_ga=2.41027938.1783205801.1604143762-654704522.1557233568#access-tokens-and-claims. Interestingly Package Service is public. Does it mean anyone on the ledger can download the dar file?

For the config management service, I couldn’t find a way to setTimeModel using com.daml.ledger.rxjava.DamlLedgerClient. I’m stuck at

DamlLedgerClient client = DamlLedgerClient.newBuilder(ledgerhost, ledgerport).build();
LedgerConfigurationClient cc = client.getLedgerConfigurationClient();

I’m not sure how to proceed from here. Do I have to use GRPC? I saw a number of clients from com.daml.ledger.rxjava.DamlLedgerClient I could create. But couldn’t find one for party management. Is that also a GRPC only implementation?
Below are the clients I found in DamlLedgerClient.

LedgerConfigurationClient
CommandSubmissionClient
CommandClient
ActiveContractSetClient
CommandCompletionClient
LedgerIdentityClient
PackageClient
TimeClient
TransactionsClient

1 Like
#5

For your first question, yes anyone can download packages. DAML code is intended to be public.

As for your second question, you are right that the config management service is not exposed in a nice way in the Java bindings at the moment. However, you can access services directly reasonably easily. @bernhard provided an example of this for the party management service in Java Bindings do not have all Ledger API services. I’ve opened Expose config management service in Java bindings · Issue #7877 · digital-asset/daml · GitHub to expose this is in a nicer way in the Java bindings.

2 Likes
#6

Just to clarify: all DAML code on the participant node is public in the sense that it’s visible to all the parties hosted on that node. But depending on the ledger, not all the participant nodes connected to the same ledger need to have all the DAML packages. For example, Canton-enabled participant nodes enable you to selectively share and whitelist DAR packages, though there’s some on-by-default automagic that shares and whitelists packages by default for convenience reasons.

2 Likes
#7

Thanks for the info. Is there a sandbox with Canton? I checked Canton sample and it seems that the sample is an all in one package. At this stage, can I run two sandboxes and link them with Canton?

1 Like
#8

There is a Canton sandbox in the sense that you can start a topology with one or more participant nodes in-process and even in-memory if you wish; the default topology in the getting strated tutorial does exactly that.

You can then later connect two such “sandboxes” if you wish. However, you cannot connect two existing existing non-Canton sandboxes using Canton, it’s not an add-on in that sense. You’d first have to migrate the data to a Canton-enabled version. We have some preliminary support for that (see https://www.canton.io/docs/stable/user-manual/usermanual/console.html#participant-repair) but it’s still very much rough around the edges.

2 Likes