When developing Daml applications using SDK tools, your local setup will most likely not verify any authorization - by default, any valid ledger API request will be accepted by the sandbox.
To run your application against a deployed ledger, you will need to add authorization.
The Ledger API is used to request changes to the ledger (e.g., “Alice wants to exercise choice X on contract Y”), or to read data from the ledger (e.g., “Alice wants to see all active contracts”).
What requests are valid is defined by integrity and privacy parts the Daml Ledger Model. This model is defined in terms of Daml parties, and does not require any cryptographic information to be sent along with requests.
In particular, this model does not talk about authentication (“Is the request claiming to come from Alice really sent by Alice?”) and authorization (“Is Alice authorized to add a new Daml package to the ledger?”).
In practice, Daml ledgers will therefore need to add authentication to the ledger API.
Depending on the ledger topology, a Daml ledger may consist of multiple participant nodes, each having its own ledger API server. Each participant node typically hosts different Daml parties, and only sees data visible to the parties hosted on that node (as defined by the Daml privacy model).
For more details on Daml ledger topologies, refer to the Daml Ledger Topologies documentation.
How authentication is set up on a particular ledger is defined by the ledger operator. However, most authentication setups share the following pattern:
First, the Daml application contacts a token issuer to get an access token. The token issuer verifies the identity of the requesting user (e.g., by checking the username/password credentials sent with the request), looks up the privileges of the user, and generates a signed access token describing those privileges.
Then, the Daml application sends the access token along with each ledger API request. The Daml ledger verifies the signature of the token (to make sure it has not been tampered with), and then checks that the privileges described in the token authorize the given ledger API request.
Authenticationis the process of confirming an identity.
Authorizationis the process of checking permissions to access a resource.
access token) is a tamper-proof piece of data that contains security information, such as the user identity or its privileges.
token issueris a service that generates tokens. Also known as “authentication server” or “Identity and Access Management (IAM) system”.
Access tokens and claims¶
Access tokens contain information about the capabilities held by the bearer of the token. This information is represented by a claim to a given capability.
The claims can express the following capabilities:
public: ability to retrieve publicly available information, such as the ledger identity
admin: ability to interact with admin-level services, such as package uploading and party allocation
canReadAs(p): ability to read information off the ledger (like the active contracts) visible to the party
canActsAs(p): same as
canReadAs(p), with the added ability of issuing commands on behalf of the party
The following table summarizes what kind of claim is required to access each Ledger API endpoint:
|Ledger API service||Endpoint||Required claim|
|ActiveContractsService||GetActiveContracts||for each requested party p: canReadAs(p)|
|CommandSubmissionService||Submit||for submitting party p: canActAs(p)|
|CompletionStream||for each requested party p: canReadAs(p)|
|CommandService||All||for submitting party p: canActAs(p)|
|All (except LedgerEnd)||for each requested party p: canReadAs(p)|
Access tokens may be represented differently based on the ledger implementation.
To learn how these claims are represented in the Sandbox, read the sandbox documentation.
Getting access tokens¶
To learn how to receive access tokens for a deployed ledger, contact your ledger operator. This may be a manual exchange over a secure channel, or your application may have to request tokens at runtime using an API such as OAuth.
To learn how to generate access tokens for the Sandbox, read the sandbox documentation.
Using access tokens¶
To learn how to use access tokens in the Scala bindings, read the Scala bindings authorization documentation.