mirror of
https://github.com/digital-asset/daml.git
synced 2024-09-20 01:07:18 +03:00
Improve auth docs (#3804)
- Document claims and what is required to access each service - Refer to claims documentation in the JWT docs for the sandbox - Fix a few typos - Specify a single padding value for all table elements (CSS) CHANGELOG_BEGIN - [Documentation] Added documentation for authorization claims CHANGELOG_END
This commit is contained in:
Stefano Baghino
GitHub
parent
a995872c7d
commit
e296cebada
@ -44,12 +44,12 @@ 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 priviledges of the user,
|
||||
and generates a signed access token describing those priviledges.
|
||||
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 priviledges described in the token authorize the given ledger API request.
|
||||
and then checks that the privileges described in the token authorize the given ledger API request.
|
||||
|
||||
.. image:: ./images/Authentication.svg
|
||||
|
||||
@ -57,9 +57,64 @@ Glossary:
|
||||
|
||||
- ``Authentication`` is the process of confirming an identity.
|
||||
- ``Authorization`` is the process of checking permissions to access a resource.
|
||||
- A ``token`` is a tamper-proof piece of data that contains security information, such as the user identity or its priviledges.
|
||||
- A ``token`` (or ``access token``) is a tamper-proof piece of data that contains security information, such as the user identity or its privileges.
|
||||
- A ``token issuer`` is a service that generates tokens. Also known as "authentication server" or "Identity and Access Management (IAM) system".
|
||||
|
||||
.. _authentication-claims:
|
||||
|
||||
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 user allocation
|
||||
- ``canReadAs(p)``: ability to read information off the ledger (like the active contracts) visible to the party ``p``
|
||||
- ``canActsAs(p)``: same as ``canReadAs(p)``, with the added ability of issuing commands on behalf of the party ``p``
|
||||
|
||||
The following table summarizes what kind of claim is required to access each Ledger API endpoint:
|
||||
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| Ledger API service | Endpoint | Required claim |
|
||||
+=====================================+============================+==========================================+
|
||||
| LedgerIdentityService | GetLedgerIdentity | public |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| ActiveContractsService | GetActiveContracts | for each requested party p: canReadAs(p) |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| CommandSubmissionService | Submit | for submitting party p: canActAs(p) |
|
||||
| +----------------------------+------------------------------------------+
|
||||
| | CompletionEnd | public |
|
||||
| +----------------------------+------------------------------------------+
|
||||
| | CompletionStream | for each requested party p: canReadAs(p) |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| CommandService | All | for submitting party p: canActAs(p) |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| LedgerConfigurationService | GetLedgerConfiguration | public |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| PackageService | All | public |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| PackageManagementService | All | admin |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| PartyManagementService | All | admin |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| ResetService | All | admin |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| TimeService | GetTime | public |
|
||||
| +----------------------------+------------------------------------------+
|
||||
| | SetTime | admin |
|
||||
+-------------------------------------+----------------------------+------------------------------------------+
|
||||
| TransactionService | LedgerEnd | public |
|
||||
| +----------------------------+------------------------------------------+
|
||||
| | 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 :ref:`sandbox <sandbox-authentication>` documentation.
|
||||
|
||||
Getting access tokens
|
||||
*********************
|
||||
|
||||
@ -67,10 +122,9 @@ To learn how to receive access tokens for a deployed ledger, contact your ledger
|
||||
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 <https://oauth.net/2/>`__.
|
||||
|
||||
To learn how to generate access tokens for a local sandbox,
|
||||
To learn how to generate access tokens for the Sandbox,
|
||||
read the :ref:`sandbox <sandbox-authentication>` documentation.
|
||||
|
||||
|
||||
Using access tokens
|
||||
*******************
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ Sandbox can also be run manually as in this example:
|
||||
_\ \/ _ `/ _ \/ _ / _ \/ _ \\ \ /
|
||||
/___/\_,_/_//_/\_,_/_.__/\___/_\_\
|
||||
initialized sandbox with ledger-id = sandbox-16ae201c-b2fd-45e0-af04-c61abe13fed7, port = 6865,
|
||||
dar file = DAR files at List(/Users/donkeykong/temp/da-sdk/test/Main.dar), time mode = Static, daml-engine = {}
|
||||
dar file = DAR files at List(/Users/damluser/temp/da-sdk/test/Main.dar), time mode = Static, daml-engine = {}
|
||||
Initialized Static time provider, starting from 1970-01-01T00:00:00Z
|
||||
listening on localhost:6865
|
||||
|
||||
@ -31,7 +31,7 @@ Here, ``daml sandbox`` tells the SDK Assistant to run ``sandbox`` from the activ
|
||||
|
||||
.. note::
|
||||
|
||||
The scenario is used for testing and development only, and is not supported by production DAML Ledgers. It is therefore unadvisable to rely on scenarios for ledger initialization.
|
||||
The scenario is used for testing and development only, and is not supported by production DAML Ledgers. It is therefore inadvisable to rely on scenarios for ledger initialization.
|
||||
|
||||
``submitMustFail`` is only supported by the test-ledger used by ``daml test`` and the IDE, not by the Sandbox.
|
||||
|
||||
@ -88,7 +88,9 @@ use one of the following command line options:
|
||||
Token payload
|
||||
=============
|
||||
|
||||
The JWT payload has the following schema:
|
||||
JWTs express claims which are documented in the :ref:`authentication <authentication-claims>` documentation.
|
||||
|
||||
The following is an example of a valid JWT payload:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -106,9 +108,9 @@ where
|
||||
|
||||
- ``ledgerId``, ``participantId``, ``applicationId`` restricts the validity of the token to the given ledger, participant, or application
|
||||
- ``exp`` is the standard JWT expiration date (in seconds since EPOCH)
|
||||
- ``admin`` determines whether the token bearer is authorized to use admin endpoints of the ledger API
|
||||
- ``actAs`` lists all DAML parties the token bearer can act as (e.g., as submitter of a command) and read data for
|
||||
- ``readAs`` lists all DAML parties the token bearer can read data for
|
||||
- ``admin``, ``actAs`` and ``readAs`` bear the same meaning as in the :ref:`authentication <authentication-claims>` documentation
|
||||
|
||||
The ``public`` claim is implicitly held by anyone bearing a valid JWT (even without being an admin or being able to act or read on behalf of any party).
|
||||
|
||||
Generating tokens
|
||||
=================
|
||||
@ -119,7 +121,7 @@ To generate RSA keys for testing purposes, use the following command
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
openssl req -nodes -new -x509 -keyout sandbox.key -out sandbox.crt
|
||||
openssl req -nodes -new -x509 -keyout sandbox.key -out sandbox.crt
|
||||
|
||||
which generates the following files:
|
||||
|
||||
@ -129,6 +131,6 @@ which generates the following files:
|
||||
Command-line reference
|
||||
**********************
|
||||
|
||||
To start Sandbox, run: ``sandbox [options] <archive>...``
|
||||
To start Sandbox, run: ``sandbox [options] <archive>...``.
|
||||
|
||||
To see all the available options, run ``daml sandbox --help``
|
||||
To see all the available options, run ``daml sandbox --help``.
|
||||
|
||||
4
docs/theme/sass/_theme_layout.sass
vendored
4
docs/theme/sass/_theme_layout.sass
vendored
@ -2220,7 +2220,7 @@ body
|
||||
text-transform: uppercase
|
||||
border-bottom: 1px solid #dddddd
|
||||
color: #3A478F
|
||||
padding: 22px 23px 22px 0
|
||||
padding: 22px 23px 22px 23px
|
||||
background-color: #ffffff
|
||||
|
||||
&:first-child
|
||||
@ -2229,7 +2229,7 @@ body
|
||||
tr
|
||||
td
|
||||
border: none
|
||||
padding: 27px 23px 27px 0
|
||||
padding: 27px 23px 27px 23px
|
||||
color: #3A478F
|
||||
white-space: normal
|
||||
vertical-align: top
|
||||
|
||||
Loading…
Reference in New Issue
Block a user