From 91b91cb43362a0e62a86b9bd9066208c6c357c01 Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Tue, 17 Nov 2026 13:35:36 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20move=20integration=20docs=20to=20the=20?= =?UTF-8?q?wiki=20(v5.4=20backport=20of=20#4672=E2=80=93#4681)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Landing note linking the wiki book "Implementing a Nuts spec v1 use case". - did.rst: DID background to the wiki; describe the did:nuts documents the node creates. - JSON-LD page to the wiki; list the built-in contexts in verifiable-credentials.rst. - vc.rst removed: search matching rules and issue example in the VCR v2 API spec. - Getting started 4-6 removed (customer integration, authentication, authorizations, connecting the EHR): on the wiki. - Page 3: Care Organizations section replaced by a link to the wiki. Assisted by AI --- docs/_static/vcr/vcr_v2.yaml | 44 +- docs/index.rst | 5 +- .../deployment/verifiable-credentials.rst | 15 +- .../getting-started/3-configure-your-node.rst | 17 +- .../getting-started/4-connecting-crm.rst | 276 --------- .../getting-started/5-authentication.rst | 531 ------------------ .../6-adding-authorizations.rst | 245 -------- .../getting-started/6-connecting-ehr.rst | 86 --- docs/pages/integrating/vc.rst | 148 ----- docs/pages/technology/did.rst | 90 +-- docs/pages/technology/jsonld.rst | 15 - 11 files changed, 108 insertions(+), 1364 deletions(-) delete mode 100644 docs/pages/getting-started/4-connecting-crm.rst delete mode 100644 docs/pages/getting-started/5-authentication.rst delete mode 100644 docs/pages/getting-started/6-adding-authorizations.rst delete mode 100644 docs/pages/getting-started/6-connecting-ehr.rst delete mode 100644 docs/pages/integrating/vc.rst delete mode 100644 docs/pages/technology/jsonld.rst diff --git a/docs/_static/vcr/vcr_v2.yaml b/docs/_static/vcr/vcr_v2.yaml index 59cf2067c4..924b57eabd 100644 --- a/docs/_static/vcr/vcr_v2.yaml +++ b/docs/_static/vcr/vcr_v2.yaml @@ -51,11 +51,25 @@ paths: operationId: "searchVCs" requestBody: required: true - description: > + description: | Searching for VCs is done by passing a JSON-LD document as query. Each field in the request body must be present in the VC in order for it to be passed as result. Different JSON-LD contexts can be used allowing for different JSON formats. Consult the node documentation on the supported contexts. The type of the credential must contain "VerifiableCredential" and the additional Nuts credential type that matches the credentialSubject context. + + The node does not search on `@context` and `type`. + So a query with only these two returns all credentials. + To find specific credentials, add fields the credential must have, e.g. `credentialSubject.organization.name`. + + Matching rules: + - by default a value must match exactly. + - `"*"` matches any credential in which the field is present (non-empty). + - a value ending with `*` matches values that start with the given string, e.g. `Hospital Amst*`. + - `*` anywhere else in a value is matched as-is. + - wildcards only work on strings. + - the query can contain only one `credentialSubject`. + + By default only credentials of trusted issuers are returned, see `searchOptions`. content: application/json: schema: @@ -127,11 +141,37 @@ paths: $ref: '#/components/schemas/IssueVCRequest' responses: "200": - description: "New VC has been created successfully. Returns the Verifiable Credential." + description: | + New VC has been created successfully. Returns the Verifiable Credential. + For `ldp_vc` credentials the node adds the `id`, `issuanceDate` and `proof`. content: application/json: schema: $ref: '#/components/schemas/VerifiableCredential' + examples: + "did:nuts (ldp_vc)": + value: + { + "@context": ["https://www.w3.org/2018/credentials/v1", "https://nuts.nl/credentials/v1"], + "id": "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY#a1d8ee3f-f404-44d5-bd07-71d3b144ce54", + "type": ["NutsOrganizationCredential", "VerifiableCredential"], + "issuer": "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY", + "issuanceDate": "2021-03-05T09:37:05.732811+01:00", + "credentialSubject": { + "id": "did:nuts:9UKf9F9sRtiq4gR3bxfGQAeARtJeU8jvPqfWJcFP6ziN", + "organization": { + "name": "Zorggroep de Nootjes", + "city": "Amandelmere" + } + }, + "proof": { + "type": "JsonWebSignature2020", + "created": "2021-03-05T09:37:05.732811+01:00", + "proofPurpose": "assertionMethod", + "verificationMethod": "did:nuts:B8PUHs2AUHbFF1xLLK4eZjgErEcMXHxs68FteY7NDtCY#gSEtbS2dOsS9PSrV13RwaZHz3Ps6OTI14GvLx8dPqgQ", + "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..s6lxJa7pOpqlhcWhJoKRMJIJiD4i+IUkfmhy+rUvNzZayVHAq+lZaFxBsv9rQCe0ewpZq/6z3hSUOURo6mnHhg==" + } + } "400": description: &issueVC400 One or more of the given parameters are invalid content: diff --git a/docs/index.rst b/docs/index.rst index 3f6970f16a..ca3adec501 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,6 +4,10 @@ Nuts documentation ################## +This documentation is for deploying and operating the Nuts node. +How to implement a use case with Nuts v5 (Nuts spec v1, ``did:nuts``) and integrate the Nuts node with your EHR is on the wiki: `Implementing a Nuts spec v1 use case `_. +Background information is on the `Nuts wiki `_. + .. toctree:: :maxdepth: 1 :caption: Getting Started: @@ -18,7 +22,6 @@ Nuts documentation pages/integrating/api.rst pages/integrating/api-authentication.rst - pages/integrating/vc.rst pages/integrating/faq-errors.rst pages/release_notes.rst pages/roadmap.rst diff --git a/docs/pages/deployment/verifiable-credentials.rst b/docs/pages/deployment/verifiable-credentials.rst index ba9a7f52b1..33950542ad 100644 --- a/docs/pages/deployment/verifiable-credentials.rst +++ b/docs/pages/deployment/verifiable-credentials.rst @@ -61,6 +61,19 @@ Or it can fetch the context definition from disk, using a mapping from url to pa The default contexts can be accessed using the embedded file system `assets/contexts`. The contents of this directory can be found on Github: The default loaded contexts can be downloaded from the `Github repo `_. +The node uses JSON-LD contexts to normalize a credential when it creates or verifies its proof, and to search credentials (``POST /internal/vcr/v2/search``). +So the node must know every context a credential uses; otherwise it can't verify or search it. +Context URLs are identifiers: they don't have to resolve, as long as the node has a local mapping for them. + +Built-in contexts (mapped to local files by default, see ``jsonld.contexts.localmapping``): + +- ``https://www.w3.org/2018/credentials/v1``: W3C Verifiable Credentials +- ``https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json``: ``JsonWebSignature2020`` proofs +- ``https://schema.org`` +- ``https://nuts.nl/credentials/v1``: Nuts credentials such as ``NutsOrganizationCredential`` and ``NutsAuthorizationCredential`` + +Background on JSON-LD in Nuts is on the `wiki `_. + Example configuration ^^^^^^^^^^^^^^^^^^^^^ @@ -91,7 +104,7 @@ Local mappings can be used to pin a version of a context, so no unseen changes c Searching and indexing ^^^^^^^^^^^^^^^^^^^^^^ -Searching for custom credentials works just as Nuts provided credentials as described in :ref:`searching-vcs`. Note however that the extra fields in the `credentialSubject` added by the custom credential are not indexed by the credential store. Searching for these fields is notably slower (depending on the query and amount of custom credentials). If this becomes a problem, inform the Nuts development team so an appropriate solution can be found. +Searching for custom credentials works just as Nuts provided credentials as described on the `wiki `_. Note however that the extra fields in the `credentialSubject` added by the custom credential are not indexed by the credential store. Searching for these fields is notably slower (depending on the query and amount of custom credentials). If this becomes a problem, inform the Nuts development team so an appropriate solution can be found. Resources ^^^^^^^^^ diff --git a/docs/pages/getting-started/3-configure-your-node.rst b/docs/pages/getting-started/3-configure-your-node.rst index a6f95d59b6..22554d479a 100644 --- a/docs/pages/getting-started/3-configure-your-node.rst +++ b/docs/pages/getting-started/3-configure-your-node.rst @@ -184,18 +184,7 @@ It will tell you: You're now set up to exchange data with other nodes. -Care Organizations -****************** +Next steps +********** -The DID documents of your care organizations you (as a vendor) want to expose on the Nuts network need to be associated -with your node DID document (a.k.a. vendor DID) through the ``NutsComm`` endpoint. -Its recommended to register the actual ``NutsComm`` endpoint on your vendor DID document (as explained in the previous section), -and register a reference to this endpoint on the DID documents of your vendor's care organizations: - -.. code-block:: text - - POST /internal/didman/v1/did//endpoint - { - "type": "NutsComm", - "endpoint": "/serviceEndpoint?type=NutsComm" - } +To set up DIDs for your care organizations and implement a use case, see `Implementing a Nuts spec v1 use case `_ on the wiki. diff --git a/docs/pages/getting-started/4-connecting-crm.rst b/docs/pages/getting-started/4-connecting-crm.rst deleted file mode 100644 index f2134677d7..0000000000 --- a/docs/pages/getting-started/4-connecting-crm.rst +++ /dev/null @@ -1,276 +0,0 @@ -.. _connecting-crm: - -Getting Started on customer integration -####################################### - -This getting started manual assumes a vendor sells services to its customers. -The vendor manages the presence of those customers on the Nuts network through the Nuts registry. -It's very likely the vendor has software to manage customer environments. We'll call it a *CRM* where the *customers* part relates to organizations and not people. -This does not mean that a stand-alone installation isn't supported. In that case the vendor and organization are the same. - -The Nuts registry enables service discovery for organizations. The registry identifies organizations through their :ref:`DID `. -The DIDs are unique identifiers which are generated when the organization is registered in the Nuts registry. -After creation of the DID the CRM should store and map it to its customer record, so it can refer to it when updating the customer's DID Document and issue Verifiable Credentials. - -All APIs used in the following chapters are documented at the :ref:`API ` page. -Open API Spec files are available for generating client code. - -Vendor integration -****************** - -As a vendor, you're in power of: - -- running a Nuts node -- handling organization key material -- updating the organization DID Document -- defining service endpoints -- issuing name credentials for organizations -- trusting other vendors - -The last three points require a setup where a vendor DID (node DID) is created. This DID will act as the controller of all organization DID Documents. -This will allow for reuse of service endpoints and issuance of Verifiable Credentials. -Since every DID issuing Verifiable Credentials must be trusted individually, it's easier for other vendors when the vendor uses a single DID for issuing credentials. - -Create and store a vendor DID -============================= - -Your CRM must store the DIDs created for your vendor and your customers. A DID is a string similar to: - -.. code-block:: text - - did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9 - -The DID we're about to create is your *vendor DID* (a.k.a node DID). It will be used in all of the next steps. -For the API calls that will need to be made to the Nuts node, we'll use ```` as the address where the internal API's are exposed. -Consult the :ref:`configuration reference ` on how to configure the node address. - -.. note:: - - If you already created your node DID you can skip this step. - -.. code-block:: text - - POST /internal/vdr/v1/did - { - "selfControl": true, - "keyAgreement": true, - "assertionMethod": true, - "capabilityInvocation": true - } - -The request above instructs the node to create a new DID and DID Document. The DID Document will be published to all other nodes. -The node will generate a new keypair and store it in the crypto backend. -The options above will instruct the node to allow the DID Document to be changed by itself (``selfControl = true`` AND ``capabilityInvocation = true``) and that the DID can be used to issue credentials (``assertionMethod = true``). -If all is well, the node will respond with a DID Document similar to: - -.. code-block:: json - - { - "@context": [ "https://www.w3.org/ns/did/v1" ], - "id": "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9", - "verificationMethod": [ - { - "id": "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw", - "controller": "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9", - "type": "JsonWebKey2020", - "publicKeyJwk": { - "crv": "P-256", - "x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8", - "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4", - "kty": "EC" - } - }], - "capabilityInvocation": [ - "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw" - ], - "assertion": [ - "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw" - ], - "keyAgreement": [ - "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw" - ], - "service": [] - } - -The ``id`` at the top level needs to be extracted and stored as your vendor DID. -In the example above this would be ``did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9``. -The DID Document shouldn't be stored since the Nuts node will do this for you. - -Setting vendor contact information -================================== - -Things can go wrong: a node is misbehaving or a DID Document is conflicted. -If the node operator is not resolving the problem it's extremely convenient if others can contact the node operator and relay the problem. -For this use-case, Nuts supports the registration of node contact information. The contact information will be added to a DID Document as a service. -A convenience API is available to add the contact information to a DID Document. The vendor DID should be used for this. - -.. code-block:: text - - PUT /internal/didman/v1/did//contactinfo - { - "name": "vendor X", - "phone": "06-12345678", - "email": "info@example.com", - "website": "https://example.com" - } - -Where ```` must be replaced with the vendor DID. - -Adding endpoints -================ - -As a vendor you'll probably be hosting different services at various stages. A Nuts node API is available to easily add/remove the endpoints for these services. -Registering services is a required step since the services that will be registered for organizations will make use of these services. - -.. code-block:: text - - POST /internal/didman/v1/did//endpoint - { - "type": "example-production-api", - "endpoint": "https://api.example.com" - } - -Where ```` must be replaced with the vendor DID. The ``type`` may be freely chosen and is used as reference in the organization services. -The ``endpoint`` must be a valid endpoint (this differs per type of service). -For some services this could be a base-url. If this is the case, the bolt description will note this. - -Organization integration -************************ - -Each organization (or customer) must be registered with its own DID and DID Document. -The vendor CRM should make it possible to store a DID for each organization. -Requests that are made in the context of the organization will use the private key of the organization. -To easily control the DID Document of an organization, the vendor will be the controller. - -Create and store a customer DID -=============================== - -A DID can be created like the vendor DID: - -.. code-block:: text - - POST /internal/vdr/v1/did - { - "selfControl": false, - "controllers": [], - "assertionMethod": true, - "capabilityInvocation": false - } - -Where ```` must be replaced with the vendor DID. -The body for creating an organization DID differs from the vendor DID in the fact that the vendor DID is in control of the newly generated DID Document. -The ``assertionMethod`` is still true since it'll allow for the generation of access-tokens in the context of the organization. -The result is similar to the output of the vendor DID creation. -In this case the ``id`` must also be extracted and stored within the vendor CRM for the right organization. - -Issue a Nuts Organization Credential -==================================== - -After registering an organization, its presence on the network and in the Nuts registry is now only a DID. -In order for other organizations to find the correct DID and connected services, credentials should be issued and published over the network. -For this, the *NutsOrganizationCredential* can be issued by any vendor. -A *NutsOrganizationCredential* contains the ``name`` of the organization and the ``city`` where this name is registered as organization. -The combination of those should be unique (since duplicate names within a sector is disallowed). - -A credential can be issued with the following call: - -.. code-block:: text - - POST /internal/vcr/v2/issuer/vc - { - "type": "NutsOrganizationCredential", - "issuer": "", - "credentialSubject": { - "id": "", - "organization": { - "name": "", - "city": "" - } - }, - "visibility": "public" - } - -Where ```` must be replaced with the vendor DID, ```` must be replaced with the organization DID, ```` and ```` must be replaced with the correct information. -The API will respond with the full Verifiable Credential. It's not required to do anything with that since issued credentials can be found again. - -Trusting other vendors as issuer -================================ - -A node operator must not blindly trust all the data is published over the network. Before credentials can be found, the issuer has to be trusted. -By default, no issuers are trusted. A list of untrusted issuers can be obtained from the node through: - -.. code-block:: text - - GET /internal/vcr/v2/verifier/NutsOrganizationCredential/untrusted - -This will return a list of all DIDs that are currently not trusted. If a DID is to be trusted should be validated out-of-band, eg: by phone or video conference call. -The registered contact information for that DID could help in contacting the right party. Be aware that the provided contact information isn't verified. -So instead of asking: "is this your DID?", ask: "could you please tell me your DID?". -After a DID has been verified, it can be trusted by calling the following API: - -.. code-block:: text - - POST /internal/vcr/v2/verifier/trust - { - "issuer": "", - "credentialType": "NutsOrganizationCredential" - } - -Where ```` must be replaced with the validated DID. -It's also possible to update the ``vcr/trusted_issuers.yaml`` file located in the data directory (configured via the ``datadir`` property). -After a vendor has been trusted, any of its registered organizations should be searchable by name. - -.. note:: - - Future development will see new cryptographic means. These means could enable the organization to self-register its name. - The network should then migrate to a trust model where the issuer of those means is trusted instead of the different vendors. - -Enabling a bolt -=============== - -Organizations can be found on the network and endpoints have been defined. -Now it's time to enable specific bolts so users can start using data from other organizations. -Every bolt requires its own configuration. This configuration is known as a Compound Service on the organization's DID document. -A Compound Service defines certain endpoint types and which endpoint to use for that type. - -A Compound Service can be added with the following request: - -.. code-block:: text - - POST /internal/didman/v1/did//compoundservice - { - "type": "", - "serviceEndpoint": { - "": "/serviceEndpoint?type=", - ... - } - } - -The parameters must be replaced: - -- ```` must be replaced with the organization DID. -- ```` must be replaced with the type defined by the bolt specification. -- ```` must be replaced with the vendor DID that defines the endpoints. -- ```` must be replaced with the type required by the bolt specification. - All types defined by the specification must be added, unless stated otherwise. -- ```` must be replaced with the correct endpoint type from the vendor DID Document. - ``/serviceEndpoint?type=`` must be a valid query within the corresponding DID Document. - - -For example, the `eOverdracht sender `_ requires an ``eOverdracht-sender`` Compound Service with two endpoints: an ``oauth`` endpoint and a ``fhir`` endpoint. -The example can be added by the following request: - -.. code-block:: text - - POST /internal/didman/v1/did/did:nuts:organization_identifier/compoundservice - { - "type": "eOverdracht-sender", - "serviceEndpoint": { - "oauth": "did:nuts:vendor_identifier/serviceEndpoint?type=production-oauth", - "fhir": "did:nuts:vendor_identifier/serviceEndpoint?type=eOverdracht-sender-fhir" - } - } - -.. note:: - - As specified by `RFC006 `_, the ``type`` MUST be unique within a DID Document. diff --git a/docs/pages/getting-started/5-authentication.rst b/docs/pages/getting-started/5-authentication.rst deleted file mode 100644 index 602069e882..0000000000 --- a/docs/pages/getting-started/5-authentication.rst +++ /dev/null @@ -1,531 +0,0 @@ -.. _getting-started-authentication: - -Adding user authentication -########################## - -This getting started manual shows how to successfully use different authentication means to sign a contract. -Contracts are used within the Nuts ecosystem to identify a user to other network participants. -It also relates a user to the care organization that user is currently working for. -The signed contract is used as token to authenticate the user's (local) EHR identity to other nodes in the network and can be used as session token on the EHR. -The contract is required for every request that results in personal and/or medical data being retrieved. - -Generic requirements -******************** - -In the contract signing flow, a device or web page communicates with the Nuts node. -Therefore the Nuts node needs to be accessible from the public internet. -All APIs on the Nuts node starting with ``/public`` (without a trailing slash) must be accessible over HTTPS without any additional security measures that could prevent access by web or mobile devices. -A domain must also be available which resolves to those APIs. -The domain must be configured on the Nuts node: - -.. code-block:: yaml - - auth: - publicurl: https://example.com - -Getting a valid contract -************************ - -All signing means require a valid contract to be submitted. -You can create a contract with the following API on the Nuts node: - -.. code-block:: - - PUT /internal/auth/v1/contract/drawup - -With the following body: - -.. code-block:: json - - { - "type": "BehandelaarLogin", - "language": "NL", - "version": "v3", - "legalEntity": "did:nuts:7eaDstczhnigW9uW1JRzYF2u5KhTntFTnee8vGDHokD", - "validFrom": "2006-01-02T15:04:05+02:00", - "validDuration": "2h" - } - -The ``type`` must be one of the valid Nuts contract types, currently only ``BehandelaarLogin`` for Dutch and ``PractitionerLogin`` for English are supported. -The ``language`` selects the correct language, ``NL`` for Dutch and ``EN`` for English. -The ``version`` must be ``v3``. -The ``legalEntity`` must refer to the DID of the current organization. The user either selects an organization to login for, or is already logged in. -The organization must have a DID as described in :ref:`Getting Started on customer integration `. -``validFrom`` is a RFC3339 compliant time string. ``validDuration`` describes how long the contract is valid for. Time unit strings are used like ``1h`` or ``60m``, the valid time units are: "ns", "us" (or "µs"), "ms", "s", "m", "h". The local system timezone is used to format the date and time string. - -The return value looks like: - -.. code-block:: json - - { - "type": "PractitionerLogin", - "language": "EN", - "version": "v3", - "message": "EN:PractitionerLogin:v3 I hereby declare to act on behalf of CareBears located in CareTown. This declaration is valid from Monday, 2 January 2006 15:04:05 until Monday, 2 January 2006 17:04:05." - } - -The ``message`` from this result is used by the specific means. - -Signing a contract with the employee identity means -*************************************************** - -This getting started manual shows how to successfully use employee identity authentication to sign a contract. - -Basic requirements -================== - -To use the employee identity as a means for signing a contract, the following is required: - -- the user interacts with the XIS/ECD via a recent browser capable of running javascript. -- the vendor has a Nuts node running. -- the Nuts node controls a DID for the organization of the user. - -Exposed endpoints -================= - -The employee identity means uses endpoints under ``{publicurl}/public/auth/v1/means/employeeid/{sessionID}``. - -Starting a session -================== - -Start a session by calling the following API on the Nuts node: - -.. code-block:: - - POST /internal/auth/v1/signature/session - -The body for this call looks like: - -.. code-block:: json - - { - "means": "employeeid", - "payload": "" - "params": { - "employer": "did:nuts:7eaDstczhnigW9uW1JRzYF2u5KhTntFTnee8vGDHokD", - "employee": { - "identifier": "user@example.com", - "initials": "T", - "familyName": "Tester", - "roleName": "VP" - } - } - } - -Where ``message`` is the result from the contract call discussed earlier. -The ``identifier`` field must include a unique identifier for the user, for example an email address or employee number. -The ``employer`` must contain the organization DID. -All fields are mandatory except ``roleName``. ``roleName`` should contain the role the user has within the organization. -This can be a functional role but also the role used for *role based access control* if such a role is human readable. - -The result will be something like: - -.. code-block:: json - - { - "sessionID": "56098jvsldrioj230468", - "url": "https://node.example.com/public/auth/v1/means/employeeid/56098jvsldrioj230468" - } - -Displaying the web page -======================= - -The webpage served from the ``url`` field from the initiated session result needs to be shown to the user. -This can be done by using an iframe, pop-up or nested browser window (for native apps). -The application should make sure the user's attention is on the newly rendered page. -The application can also query the current status of the process by calling the session status endpoint (see below). -If the frontend of the application is viewing the status, it must do so by proxying the session status endpoint via it's backend. -This is because the session status endpoint is an internal endpoint and can only be accessed by a client application's backend. - -Getting the session result -========================== - -The result of the session can be obtained by calling: - -.. code-block:: - - GET /internal/auth/v1/signature/session/ - -The call to the Nuts node will return the following response: - -.. code-block:: json - - { - "status": "completed", - "verifiablePresentation": { - // ... - } - } - -The ``status`` field may contain any of ``[created, in-progress, completed, cancelled, errored, expired]``. -These values can be used to give the user feedback on the current status. -The presence of the ``verifiablePresentation`` in the result is the main method of checking if the signing session succeeded. -``verifiablePresentation`` is the cryptographic proof that needs to be stored in the user session. -It's required in the OAuth flow for obtaining an access token. - -.. _irma-contract: - -Signing a contract with the IRMA means -************************************** - -This getting started manual shows how to successfully use IRMA to sign a contract. - -Basic requirements -================== - -To use IRMA as a means for signing a contract, the following is required: - -- the user has the IRMA app installed on an Android or iOS device with camera and an internet connection. -- the user has retrieved the BRP and email credentials in the IRMA app. -- the user interacts with the XIS/ECD via a recent browser capable of running javascript. -- the vendor has a Nuts node running. - -IRMA flow -========= - -We use the Nuts node as IRMA server and as tool to start an IRMA session. This follows the flow as described on this `IRMA Github page `_. -The XIS/ECD will have to provide two endpoints for the frontend. One endpoint to start a session and one to get the session result. -More info on these endpoints will be provided further down. - - -Additional configuration -======================== - -The public URL will be expanded to ``{publicurl}/public/auth/irmaclient`` as IRMA path. -IRMA's ``session`` API will be mounted at that base path. -The Nuts APIs used for signing will embed this URL in the QR code shown to the user. -The javascript in the frontend will also use this URL (exposed via the QR code) to check the status of the signing session. -Therefore the domain which serves the frontend must be able to do requests to that domain. -The browser will require CORS headers to be configured on the domain configured in the Nuts node config. -This can be done by the following snippet: - -.. code-block:: yaml - - http: - default: - cors: - origin: "other.com" - -Where *other.com* is the domain serving the frontend. For development purposes ``*`` is also allowed. -If the public APIs are mounted on a different port/interface in the nuts config then the ``default`` key should be changed to ``alt.public`` in the example above. - -Setting up the frontend -======================= - -For the frontend we'll be using the `irma-frontend-packages `_ javascript library. -More info on how to use this library can be found on ``_. -You can choose to load the IRMA frontend packages javascript via an HTML tag, in which case you'll need to build the javascript file yourself given the instructions on ``_ or you can choose to use ``npm``: - -.. code-block:: json - - "dependencies": { - "@privacybydesign/irma-frontend": "^0.3.3" - } - -Make sure you use the latest version. - -IRMA allows for multiple frontends to be used. The most important ones are the *web* and *popup* frontends. -The *web* frontend allows for embedding the IRMA web component within a html element. -The *popup* frontend will render a new component that will render on top of the rest of the website. -This manual will use the *popup* frontend. - -A complete example: - -.. code-block:: javascript - - let options = { - // Developer options - debugging: true, - - // Front-end options - language: 'en', - - // customize textual components - translations: { - header: "Sign your contract" - }, - - // Back-end options - session: { - // Point to your web backend - url: '/web/auth', - - // The request that will be send to the backend: - start: { - method: 'POST', - headers: { - 'Content-Type': 'application/json' - }, - body: JSON.stringify(this.some_data) - }, - - // required to translate Nuts specific return values - mapping: { - sessionPtr: r => r.sessionPtr.clientPtr, - sessionToken: r => r.sessionID - } - } - }; - - // we'll use the popup frontend - let irmaPopup = irma.newPopup(options); - - // start the interaction - irmaPopup.start() - .then(result => { - console.log("success!") - console.log(response) - }) - .catch(error => { - if (error === 'Aborted') { - console.log('Aborted'); - return; - } - console.error("error", error); - }) - .finally(() => irmaPopup = irma.newPopup(options)); - } - -Lets break this down into parts. - -.. code-block:: javascript - - // Developer options - debugging: true, - -Is used to enabling debugging. The IRMA library will output more information helpful for development. - -.. code-block:: javascript - - // Front-end options - language: 'en', - - // customize textual components - translations: { - header: "Sign your contract" - }, - -Sets the language to english which will set some default textual representations on the IRMA web component. -The ``translations`` configuration option can be used to change each of the textual representation on the IRMA web component. -In this case, only the header is changed. - -.. code-block:: javascript - - // Back-end options - session: { - // Point to your web backend - url: '/web/auth', - - // The request that will be send to the backend: - start: { - method: 'POST', - headers: { - 'Content-Type': 'application/json' - }, - body: JSON.stringify(this.some_data) - }, - - // required to translate Nuts specific return values - mapping: { - sessionPtr: r => r.sessionPtr.clientPtr, - sessionToken: r => r.sessionID - } - } - -The ``session`` object contains all the technical parts to connect the IRMA javascript library to your backend. -The contents of the ``start`` object configures the initial request to start a signing session. You can control the type of request and the contents. -In this case, some data from the frontend is sent as JSON. This is optional and no particular data is required. -The ``url``, in this case ``/web/auth``, must be set so the frontend can access the following URLs: - -.. code-block:: - - /session - /session//result - -These URLs must both be available on the backend. For the example above this means that both ``/web/auth/session/`` and ``/web/auth/session//result`` are available. The ```` is the token that will be returned by the call to ``/session/``. -How to parse the result of that call and extract the token is done via the ``mapping`` object. - -The ``mapping`` object is a map where two keys are expected: ``sessionPtr`` and ``sessionToken``. -``sessionPtr`` must point to the data that is used to render the QR code. -``sessionToken`` must point to the sessionID token used to get the result (IRMA uses the term `sessionToken` for `sessionID` ). - -Setting up the backend -====================== - -As discussed in the previous chapter, the backend is required to expose two APIs to the frontend: - -.. code-block:: - - /session - /session//result - -No particular security context is required, you may require a user session if needed. - -Starting a session ------------------- - -The ``/session`` API is used to start a session. -To start a session at the Nuts node, a valid contract has to be drawn up first. -You can create such a contract with the following API on the Nuts node: - -.. code-block:: - - PUT /internal/auth/v1/contract/drawup - -With the following body: - -.. code-block:: json - - { - "type": "BehandelaarLogin", - "language": "NL", - "version": "v3", - "legalEntity": "did:nuts:90348275fjasihnva4857qp39hn", - "validFrom": "2006-01-02T15:04:05+02:00", - "validDuration": "2h" - } - -The ``type`` must be one of the valid Nuts contract types, currently only ``BehandelaarLogin`` for Dutch and ``PractitionerLogin`` for English are supported. -The ``language``` selects the correct language, ``NL`` for Dutch and ``EN`` for english. The ``version`` must be ``v3``. -The ``legalEntity`` must refer to the DID of the current organization. The user either selects an organization to login for, or is already logged in. -The organization must have a DID as described in :ref:`Getting Started on customer integration `. -``validFrom`` is a RFC3339 compliant time string. ``validDuration`` describes how long the contract is valid for. Time unit strings are used like ``1h`` or ``60m``, the valid time units are: "ns", "us" (or "µs"), "ms", "s", "m", "h". The local system timezone is used to format the date and time string. - -The return value looks like: - -.. code-block:: json - - { - "type": "PractitionerLogin", - "language": "EN", - "version": "v3", - "message": "EN:PractitionerLogin:v3 I hereby declare to act on behalf of CareBears located in CareTown. This declaration is valid from Monday, 2 January 2006 15:04:05 until Monday, 2 January 2006 17:04:05." - } - -The ``message`` from this result is used in the next part. -Start an IRMA session by calling the following API on the Nuts node: - -.. code-block:: - - POST /internal/auth/v1/signature/session - -The body for this call looks like: - -.. code-block:: json - - { - "means": "irma", - "payload": "" - } - -Where ``message`` is the result from the contract call. -The result from this call must be passed directly to the frontend. -If any transformation is done, the ``mapping`` setting in the frontend must be changed accordingly. - -Getting the session result --------------------------- - -The IRMA javascript frontend library will check for the status of the signing session. When the session has been completed it'll call the following url: - -.. code-block:: - - GET /session//result - -where ```` is the base url configured under ``session.url`` in the javascript options and ```` is the token returned by the previous call. -The backend must implement this API, the implementation must call the following API on the Nuts node: - -.. code-block:: - - GET /internal/auth/v1/signature/session/ - -Any error in calling this service need to be relayed to the frontend. This will instruct the user on why things went wrong and what to do next. -The call to the Nuts node will return the following response: - -.. code-block:: json - - { - "status": "completed", - "verifiablePresentation": { - // ... - } - } - -The ``status`` field has a different content when a different signing means is used. -The presence of the ``verifiablePresentation`` in the result is the main method of checking if the signing session succeeded. -``verifiablePresentation`` is the cryptographic proof that needs to be stored in the user session. -It's required in the OAuth flow for obtaining an access token. - -Verifiable presentation validity -******************************** - -The backend should check if the signed contract (verifiable presentation) is still valid when using it. -The validity can be checked by calling the following API with the verifiable presentation at the place of ````: - -.. code-block:: - - PUT /internal/auth/v1/signature/verify - -with - -.. code-block:: json - - { - "checkTime": "2006-01-02T15:54:05+02:00", - "verifiablePresentation": "" - } - - -It will return a structure similar to: - -.. code-block:: json - - { - "validity": true, - "vpType": "NutsIrmaPresentation", - "issuerAttributes": { - "pbdf.gemeente.personalData.initials": "T", - "pbdf.gemeente.personalData.prefix": "", - "pbdf.gemeente.personalData.familyname": "Tester", - "pbdf.sidn-pbdf.email.email": "tester@example.com" - }, - "credentials": { - "organization": "CareBears", - "validFrom": "2006-01-02T15:04:05+02:00", - "validTo": "2006-01-02T17:04:05+02:00" - } - } - -The ``validity`` will indicate its validity. An expired contract is considered invalid. - -Audit log requirements -********************** - -Information in the access token can be used to fulfill audit log requirements for protected resources. -An access token issued by the Nuts node can be introspected using the introspection API (RFC7662): - -.. code-block:: - - POST /internal/auth/v1/accesstoken/introspect - -The POST body is ``application/x-www-form-urlencoded`` encoded - -.. code-block:: - - token= - -The result will return the following identifying properties if user authentication was present in the access token: - -- username -- initials -- family_name -- assurance_level - -``username`` can be used as a unique user identifier. It will be filled with an email address or other identifier, issued by the user's employer. - -.. note:: - - The listed properties are the minimal result, additional properties may be present in the access token. - -.. note:: - - This is not yet the case for the UZI means. \ No newline at end of file diff --git a/docs/pages/getting-started/6-adding-authorizations.rst b/docs/pages/getting-started/6-adding-authorizations.rst deleted file mode 100644 index 4638eee751..0000000000 --- a/docs/pages/getting-started/6-adding-authorizations.rst +++ /dev/null @@ -1,245 +0,0 @@ -.. _getting-started-authorizations: - -Getting started with Authorizations -################################### - -Authorization is one of the three core concepts of Nuts (the others being identification and addressing). - -Introduction -************ - -Authorization comes in the form of a `NutsAuthorizationCredential `_. -An authorization credential is a privately distributed credential that answers: - -- which **custodian** controls the resources -- to which **patient** do the resources belong to -- which **actor** may access the resources -- what is the **scope** of the authorization -- on what **legal base** is the authorization provided -- which individual **resources** may be accessed - -Authorization credentials are issued by the same party that will also control the access to the resources. - -Bolt -==== - -A Bolt is a functional and technical specification that translates a care process to technical requirements. -An authorization is created for a particular Bolt. A Bolt specifies what the possible values of ``purposeOfUse`` can be. -Each value corresponds to an access policy defined by the Bolt. -Creating an authorization credential that is not according to a Bolt specification will have little effect or will even hinder interoperability. -Particular requirements for a Bolt are not validated by the node, the node will only do the validations as specified. - -Prerequisites -============= - -Since authorization credentials are privately distributed, their exchange only happens over authenticated connections. -To query authorization credentials (issued to your care organization(s)) or let the authorized party query an authorization credential you issued, -you need to configure your node's identity and ``NutsComm`` endpoint. -See :ref:`setting up your node for a network ` for how to achieve this. - -Registering a NutsAuthorizationCredential -***************************************** - -Issuing an authorization credential is similar to issuing an organization credential. Both use the same API. -New credentials will automatically receive an ``id``, ``issuanceDate``, ``context`` and ``proof``. -A DID requires a valid `assertionMethod key `_. - -The credential can be issued with the following call: - -.. code-block:: text - - POST /internal/vcr/v2/issuer/vc - { - "issuer": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv", - "type": "NutsAuthorizationCredential", - "credentialSubject": { - "id": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv", - "resources": [ - { - "path": "/patient/2250f7ab-6517-4923-ac00-88ed26f85843", - "operations": ["read"], - "userContext": true - } - ], - "purposeOfUse": "test-service", - "subject": "urn:oid:2.16.840.1.113883.2.4.6.3:123456780" - }, - "visibility": "private" - } - -As you can see, there are quite some fields to fill out. -The following paragraphs will dig deeper into the different parts. - -issuer -====== -The ``issuer`` is the resource owner. It must be a DID of an organization for which you control the private key. -The DID typically comes from your own administration, see also :ref:`Getting Started on customer integration `. - -type -==== -The ``type`` must equal to ``"NutsAuthorizationCredential"``, no exceptions. - -visibility -========== -VCs that are published to the network can be published publicly or private. -When published private, only the issuer and subject can read the contents of the VC. -VCs that contain personal information must be published privately (`visibility = private`). -When the VC is to be read by anyone on the network, it should be published publicly (`visibility = public`). - -credentialSubject.id -==================== -The ``credentialSubject.id`` is the receiver or *holder* of the credential. -It must be a DID of an organization. This DID is typically found via a search call. -The following call will search for an organization with the name *CareBears*. - -.. code-block:: text - - POST /internal/vcr/v2/search - { - "query": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "type": ["VerifiableCredential" ,"NutsOrganizationCredential"], - "credentialSubject": { - "organization": { - "name": "CareBears" - } - } - } - } - -The :ref:``VC manual `` contains some more information on how to perform searches. - -credentialSubject.purposeOfUse -============================== -The ``credentialSubject.purposeOfUse`` field will be filled with a fixed value. -A Bolt specification will describe what value to put here. - -credentialSubject.subject -========================= -The ``credentialSubject.subject`` field identifies the patient. -Resources that are scoped to a patient will have an authorization record with a patient identifier. -It's possible for authorization records to not include this field. -A Bolt specification should describe when to use this field and when not. -The contents in this example is a **urn** with a Dutch citizens number. - -credentialSubject.resources -=========================== -The resources array describes what resources may be accessed with the authorization credential. -Unless stated otherwise by the Bolt, these resources are in addition to any common resources listed by the access policy of the Bolt. -A resource has 3 members: ``path``, ``operations`` and ``userContext``. -See `the Nuts specification `_ for more detail. - -Searching for authorization credentials -*************************************** - -Authorization credentials can be used as a distributed index: *where can I find information for patient X?*. -When an access token is requested via the API, references to the relevant authorization credentials are required. - -To find the relevant authorization credentials, the credential search API can be used. -To find all authorization credentials of a single patient: - -.. code-block:: text - - POST /internal/vcr/v2/search - { - "query": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "type": ["VerifiableCredential" ,"NutsAuthorizationCredential"], - "credentialSubject": { - "id": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv", - "subject": "urn:oid:2.16.840.1.113883.2.4.6.3:123456780" - } - }, - "searchOptions": { - "allowUntrustedIssuer": true - } - } - -The call above includes a query for a particular *receiver* via the ``credentialSubject.id`` key. -This would typically be a DID from your own administration. -The second parameter defines the patient. -This example will return a list of authorization credentials where the ``credentialSubject.purposeOfUse`` field will indicate what kind of information can be retrieved. -The ``untrusted`` query parameter must be added because authorization credentials are not issued by a trusted third party but by organizations themselves. - -It can also be the case that you need to find an authorization that covers a certain request. -If you want to call ``/patient/2250f7ab-6517-4923-ac00-88ed26f85843`` for a particular Bolt, you can use: - -.. code-block:: text - - POST /internal/vcr/v2/search - { - "query": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "type": ["VerifiableCredential" ,"NutsAuthorizationCredential"], - "credentialSubject": { - "id": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv", - "purposeOfUse": "test-service", - "resources": { - "path": "/patient/2250f7ab-6517-4923-ac00-88ed26f85843" - } - } - }, - "searchOptions": { - "allowUntrustedIssuer": true - } - } - -This call will return all authorization credentials with a ``purposeOfUse`` equal to ``test-service`` that you are allowed to call for the resource located at ``/patient/2250f7ab-6517-4923-ac00-88ed26f85843`` -Any value in an authorization credential can be used as a param in the search API. -The search ``key`` requires a valid JSON path expression. - -Return values -============= - -When searching for authorization credentials, the credentials are returned as a verifiable credential. -Most of the time, you'll only need the credential identifier, available in the root ``id`` field. - -Example return value: - -.. code-block:: json - - [ - { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "credentialSubject": { - "id": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv", - "purposeOfUse": "test-service", - "resources": [ - { - "operations": [ - "read" - ], - "path": "/patient/2250f7ab-6517-4923-ac00-88ed26f85843", - "userContext": true - } - ], - "subject": "urn:oid:2.16.840.1.113883.2.4.6.3:123456780" - }, - "id": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv#314542e8-c8cc-4502-a7df-a815ac47c06b", - "issuanceDate": "2021-07-26T14:36:10.163463+02:00", - "issuer": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv", - "proof": { - "created": "2021-07-26T14:36:10.163463+02:00", - "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..k4cda7fMY05mnp4gsNJ3hNExjsSz3mqymyo4xJWkbb9-1URljVWIzPg6R62T-YETV7UXvz1X9QteuhbmoM1JLA", - "proofPurpose": "assertionMethod", - "type": "JsonWebSignature2020", - "verificationMethod": "did:nuts:JCJEi3waNGNhkmwVvFB3wdUsmDYPnTcZxYiWThZqgWKv#_3uOS5FqcyGj-cn-Yynv5epH0UVqbt_2BWXPfy0oKnU" - }, - "type": [ - "NutsAuthorizationCredential", - "VerifiableCredential" - ] - } - ] diff --git a/docs/pages/getting-started/6-connecting-ehr.rst b/docs/pages/getting-started/6-connecting-ehr.rst deleted file mode 100644 index 6bef260961..0000000000 --- a/docs/pages/getting-started/6-connecting-ehr.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _connecting-ehr: - -Getting Started on EHR integration -################################## - -This getting started manual assumes the vendor and its clients (care organizations) are set up on the Nuts Network through :ref:`connecting-crm`. -The next step is to integrate the vendor's electronic health record (EHR) with the Nuts node to execute Bolts. - -All APIs used in the following chapters are documented at the :ref:`API ` page. -There you will also find the OpenAPI specifications for generating client code. - -Resolving Bolt endpoints -************************ - -Bolts define which technical endpoints should be defined for exchanging information. -These endpoints are grouped as services which are generally named after the Bolt they support. -The Nuts registry (as described by :ref:`connecting-crm`) can be queried to find care organizations that support a particular Bolt, -and to resolve the technical endpoints associated with it. - -Searching organizations -======================= - -To find care organizations (registered in the Nuts registry) that support a specific Bolt, the search organization API can be used. -It requires the ``query`` parameter to match organization names, and optionally a ``didServiceType`` (from its DID document). -If the DID service type is supplied, the API only returns the organizations who's DID Document contains a service of that type. - -For example, the following API call searches the Nuts registry for organizations which name matches "Ziekenhuis" and have a service of type "secure-direct-messaging" on their DID Document: - -.. code-block:: text - - GET /internal/didman/v1/search/organizations?query=Ziekenhuis&didServiceType=secure-direct-messaging - -.. note:: - - The example DID service type "secure-direct-messaging" could be defined by a (fictional) "Secure Direct Messaging" Bolt to be published by organizations that allow their employees to securely chat with other organizations through Nuts. - -The API call returns a list of search results where each entry contains the organization and its last DID Document: - -.. code-block:: json - - [ - { - "didDocument": { - "@context": "https://www.w3.org/ns/did/v1", - "assertionMethod": [ - "did:nuts:JCx4c3ufdKNgaZJ4h54AghY8ZgCznptNpjHUtzvVgcvW#Cv0c4hlz4My7pKa6Wh6UN7gnTAXi5WUpNChqsUuIL1A" - ], - "controller": "did:nuts:5bSHwHtpSZfSCdCqaHvzDceEkjgNuKvTWVvQPB5DdeD9", - "id": "did:nuts:JCx4c3ufdKNgaZJ4h54AghY8ZgCznptNpjHUtzvVgcvW", - "verificationMethod": [ - /* etc */ - ], - "service": { - "type": "secure-direct-messaging", - /* etc */ - } - }, - "organization": { - "city": "Doornenburg", - "name": "Fort Pannerden" - } - } - ] - -For an organization to be returned as search results the following requirements must be met: - -- It must have an active DID Document. -- The issuer of this DID document's verifiable credential (``NutsOrganizationCredential``) must be trusted by the local node. -- The verifiable credential must not be expired or revoked. - -The ``query`` parameter is used to phonetically match the organization name: it supports partial matches and matches that sound like the given query. - -Resolving endpoints -=================== - -When an organization has been selected, the next step is to resolve the technical endpoints. -This is done by taking the compound service as specified by the Bolt and resolving its endpoint references to an actual URL endpoints. -You can use the DIDMan ``getCompoundServiceEndpoint`` API operation for this. - -Receiving Authorization Credentials -*********************************** - -Some Bolts require authorization credentials to authenticate data exchanges. These credentials are distributed privately over an authenticated connection. -To receive privately distributed credentials issued to your care organizations, -the DID documents of the care organizations need to contain a ``NutsComm`` service that references the vendor's. -See :ref:`setting up your node for a network ` for how to achieve this. \ No newline at end of file diff --git a/docs/pages/integrating/vc.rst b/docs/pages/integrating/vc.rst deleted file mode 100644 index 9c1f60b0d6..0000000000 --- a/docs/pages/integrating/vc.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. _using-vcs: - -Issuing and searching Verifiable Credentials -############################################ - -Issuing VCs -*********** - -As a node, you can issue credentials with each DID you control (whether they are trusted is a different story). -A credential is issued through the API or CLI. -The node will add sensible defaults for: - -- id -- issuanceDate -- proof - -You are required to provide the ``credentialSubject``, the ``issuer``, the ``type`` and an optional ``@context`` and ``expirationDate``. -If you do not pass a `@context`, it'll be set: ``["https://www.w3.org/2018/credentials/v1", "https://nuts.nl/credentials/v1"]``. -Note that this default does not include the latest version of the Nuts JSON-LD context. -The latest Nuts JSON-LD context can be found :ref:`here `. - -Calling `/internal/vcr/v2/issuer/vc` with - -.. code-block:: json - - { - "issuer": "did:nuts:ByJvBu2Ex21tNdn5s8FBnqmRBTCGkqRHms5ci7gKM8rg", - "type": "NutsOrganizationCredential", - "credentialSubject": { - "id": "did:nuts:9UKf9F9sRtiq4gR3bxfGQAeARtJeU8jvPqfWJcFP6ziN", - "organization": { - "name": "Because we care B.V.", - "city": "IJbergen" - } - }, - "visibility": "public" - } - -Will be expanded by the node to: - -.. code-block:: json - - { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "credentialSubject": { - "id": "did:nuts:9UKf9F9sRtiq4gR3bxfGQAeARtJeU8jvPqfWJcFP6ziN", - "organization": { - "city": "IJbergen", - "name": "Because we care B.V." - } - }, - "id": "did:nuts:ByJvBu2Ex21tNdn5s8FBnqmRBTCGkqRHms5ci7gKM8rg#a1d8ee3f-f404-44d5-bd07-71d3b144ce54", - "issuanceDate": "2021-03-05T09:37:05.732811+01:00", - "issuer": "did:nuts:ByJvBu2Ex21tNdn5s8FBnqmRBTCGkqRHms5ci7gKM8rg", - "proof": { - "created": "2021-03-05T09:37:05.732811+01:00", - "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..s6lxJa7pOpqlhcWhJoKRMJIJiD4i+IUkfmhy+rUvNzZayVHAq+lZaFxBsv9rQCe0ewpZq/6z3hSUOURo6mnHhg==", - "proofPurpose": "assertionMethod", - "type": "JsonWebSignature2020", - "verificationMethod": "did:nuts:ByJvBu2Ex21tNdn5s8FBnqmRBTCGkqRHms5ci7gKM8rg#gSEtbS2dOsS9PSrV13RwaZHz3Ps6OTI14GvLx8dPqgQ" - }, - "type": [ - "NutsOrganizationCredential", - "VerifiableCredential" - ] - } - -The `visibility` property indicates the contents of the VC are published on the network, so it can be read by everyone. - -.. _searching-vcs: - -Searching VCs -************* - -You can search for VCs by providing a VC which should be used for matching in JSON-LD format. -Searching works by posting a Verifiable Credential to `/internal/vcr/v2/search` that contains fields to match. -The operation yields an array containing the matched verifiable credentials. - -The example below searches for a `NutsOrganizationCredential` (note that the `query` field contains the credential): - -.. code-block:: json - - { - "query": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "type": ["VerifiableCredential" ,"NutsOrganizationCredential"], - "credentialSubject": { - "id": "did:nuts:SKUYYi2g88ohjhiu49Q13ZWGXvp678sjNiM7UHUCMyw", - "organization": { - "name": "Because we care B.V.", - "city": "IJbergen" - } - } - } - } - -Note the fields `@context` and `type`, these are required for making it a valid VC in JSON-LD. -In the example above they also contain Nuts specific contexts and types (since we're searching for a Nuts VC). -The fields `@context` and `type` are not used as query parameters for searching, they are required to determine the right context. -The following query does not return all `NutsOrganizationCredential` but **all** credentials. - -.. code-block:: json - - { - "query": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "type": ["VerifiableCredential" ,"NutsOrganizationCredential"], - } - } - -To find certain credentials, you'll need to add fields that are required to exist in the desired credential. -By default, matching is exact: it only returns the result when the given value exactly matches. -There are 2 other matchers for strings: -- ``"*"`` to match credential fields that contain the field (non-empty) -- ``*`` as postfix to match credential fields that start with the given string, e.g. ``Hospital Amst*`` -When ``*`` is used anywhere else in the string it won't be interpreted as wildcard and matched as-is. -Wildcards are not supported for other types than strings. - -The following example showcases both matchers: - -.. code-block:: json - - { - "query": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://nuts.nl/credentials/v1" - ], - "type": ["VerifiableCredential" ,"NutsOrganizationCredential"], - "credentialSubject": { - "organization": { - "name": "Hospital Amst*", - "city": "*" - } - } - } - } - -By default only VCs from trusted issuers are returned. You can specify the `searchOptions` field to include VCs from untrusted issuers. diff --git a/docs/pages/technology/did.rst b/docs/pages/technology/did.rst index 939cc77ee8..f6f571f1a2 100644 --- a/docs/pages/technology/did.rst +++ b/docs/pages/technology/did.rst @@ -3,51 +3,51 @@ Decentralized identifiers ######################### -Nuts uses `W3C Decentralized Identifiers `_ as a base for tracking identities. -From the W3C website: - - Decentralized identifiers (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies. In contrast to typical, federated identifiers, DIDs have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, while other parties might be used to help enable the discovery of information related to a DID, the design enables the controller of a DID to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID subject with a DID document allowing trustable interactions associated with that subject. - -Within Nuts, DIDs identify both care organizations and software vendors. All DID methods require their own specification. -The Nuts specification for the `nuts` DID method can be found on https://nuts-specification.readthedocs.io. -Nuts DIDs are designed so they represent public/private key pairs. Any party can generate and claim a key pair. -Only when information is added to the key pair, the key pair becomes important. - -DIDs can gather claims through Verifiable Credentials. This allows a DID to actually represent something known in real life. -For example: adding an organization name credential connects the key pair to the name of the organization. It connects the digital world to the real world. - -DID Documents -************* - -DIDs are backed by a *DID Document*. It defines the public keys, who can alter the document and any services related to the DID. -DID documents are automatically propagated through the network when they are created. -When DID documents are created, the DID **always** represents the public key fingerprint of the associated key. -A DID document is always created with a new key, the holder of the key can delegate the control to another DID. - -Controller -========== - -The controller of the DID document is the only one that can change the contents. It can assign other controllers, change keys, change services and revoke the DID. -When created, the DID document only has a single controller: the DID itself and the key related to it. It can choose to change add new controllers and remove existing ones. -Changes to DID documents are only accepted when the network transaction is signed with a controller's **authentication** key. - -Verification Method -=================== - -All public keys within a Nuts DID Document are listed under **verificationMethod**. - -Assertion Method -================ - -Keys referenced from the **assertionMethod** section are used to sign JWTs in the OAuth flow and for issuing *Verifiable Credentials*. - -Authentication Method -===================== - -Keys referenced from the **authentication** section are used to change the DID document and sign network transactions. +Nuts uses `W3C Decentralized Identifiers `_ (DIDs) to identify parties. +A DID is backed by a *DID Document*: it lists the public keys of the party, who can change the document (its controllers) and its services. +What DIDs are and which DID method a use case uses is described on the wiki: `Decentralized Identifiers `_. +This version of the Nuts node supports the ``did:nuts`` method, see the `did:nuts specification (RFC006) `_. + +DID Documents created by the Nuts node +************************************** + +A DID Document is created with ``POST /internal/vdr/v1/did``: + +- The DID is ``did:nuts:``, where the id is derived from a new key: the base58-encoded SHA-256 JWK thumbprint of that key. +- The DID Document is sent to all nodes through the Nuts network. +- Changes are only accepted when the network transaction is signed with a ``capabilityInvocation`` key of a controller. + +The request sets which DID controls the document and how the key is used: + +.. list-table:: + :header-rows: 1 + + * - Request field + - Default + - Effect + * - ``selfControl`` + - ``true`` + - ``true``: the DID controls its own document with the new key. ``false``: the key the DID is derived from isn't added to the document, a second new key is added instead. Only the ``controllers`` can change the document. + * - ``controllers`` + - none + - Other DIDs that can change the document, e.g. the vendor DID for a care organization's DID. + * - ``assertionMethod`` + - ``true`` + - The key signs credentials and access token requests. + * - ``capabilityInvocation`` + - ``true`` + - The key can change the DID Document. Must be ``true`` when ``selfControl`` is ``true``. + * - ``keyAgreement`` + - ``true`` + - The key is used for encryption. + * - ``authentication``, ``capabilityDelegation`` + - ``false`` + - + +All keys are EC keys (``JsonWebKey2020``). New keys are added with ``POST /internal/vdr/v1/did/{did}/verificationmethod``, see :ref:`key-rotation`. Services -======== +******** -The **services** section is used to list service endpoints. There are some endpoints that are shared amongst all services, like the **oauth** service. -But most service endpoints will be coming from specific `Bolts `_. +Use cases built on Nuts spec v1 list their endpoints as services in the DID Document. +How to register them is described on the wiki: `Set up DIDs and services `_. diff --git a/docs/pages/technology/jsonld.rst b/docs/pages/technology/jsonld.rst deleted file mode 100644 index ce821b0b76..0000000000 --- a/docs/pages/technology/jsonld.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _jsonld: - -JSON-LD -####### - -`JSON Linked Data (JSON-LD) `_ is a lightweight Linked Data format. It is easy for humans to read and write. -It is based on the already successful JSON format and provides a way to help JSON data interoperate at Web-scale. -JSON-LD is an ideal data format for programming environments, REST Web services, and unstructured databases. - -Within Verifiable Credentials, JSON-LD is used to convert it to a normalized document. Normalization is required for proof generation and validation. - -Nuts Context V1 -*************** - -https://nuts.nl/credentials/v1 \ No newline at end of file