diff --git a/.gitbook/assets/spec-relations.svg b/.gitbook/assets/spec-relations.svg index f602df9..6344190 100644 --- a/.gitbook/assets/spec-relations.svg +++ b/.gitbook/assets/spec-relations.svg @@ -1,29 +1,29 @@ - - + D - + cluster_internal - + cluster_external - + RFC001 - -RFC001 -Nuts Start Architecture + +RFC001 +Nuts Start Architecture @@ -31,398 +31,448 @@ RFC002 - -RFC002 -Authentication token + +RFC002 +Authentication token RFC002->RFC001 - - + + RFC003 - -RFC003 -OAuth2 Authorization + +RFC003 +OAuth2 Authorization RFC003->RFC001 - - + + RFC003->RFC002 - - + + - + RFC7662_EXT - - -RFC7662 -OAuth 2.0 Token Introspection + + +RFC7662 +OAuth 2.0 Token Introspection RFC003->RFC7662_EXT - - + + - + RFC7523_EXT - - -RFC7523 -JSON Web Token (JWT) Profile -for OAuth 2.0 Client Authentication and Authorization Grants + + +RFC7523 +JSON Web Token (JWT) Profile +for OAuth 2.0 Client Authentication and Authorization Grants RFC003->RFC7523_EXT - - + + - + RFC7515_EXT - - -RFC7515 -JSON Web Signature (JWS) + + +RFC7515 +JSON Web Signature (JWS) RFC003->RFC7515_EXT - - + + RFC004 - -RFC004 -Verifiable Transactional Graph + +RFC004 +Verifiable Transactional Graph RFC004->RFC001 - - + + RFC008 - -RFC008 -Certificate Structure + +RFC008 +Certificate Structure RFC004->RFC008 - - + + RFC004->RFC7515_EXT - - + + RFC005 - -RFC005 -Distributed Document Network using gRPC + +RFC005 +Distributed Document Network using gRPC RFC005->RFC004 - - + + RFC006 - -RFC006 -Distributed Registry using DIDs + +RFC006 +Distributed Registry using DIDs RFC006->RFC004 - - + + RFC006->RFC008 - - + + - + DID_EXT - - -W3C DID -Decentralized Identifiers (DIDs) v1.0 + + +W3C DID +Decentralized Identifiers (DIDs) v1.0 RFC006->DID_EXT - - + + RFC011 - -RFC011 -Verifiable Credentials + +RFC011 +Verifiable Credentials RFC011->RFC003 - - + + RFC011->RFC004 - - + + - + RFC7779_EXT - - -RFC7779 -JSON Web Signature (JWS) Unencoded Payload Option + + +RFC7779 +JSON Web Signature (JWS) Unencoded Payload Option RFC011->RFC7779_EXT - - + + - + VC_EXT - - -W3C VC -Verifiable Credentials Data Model v1.1 + + +W3C VC +Verifiable Credentials Data Model v1.1 RFC011->VC_EXT - - + + RFC012 - -RFC012 -Nuts Organization Credential + +RFC012 +Nuts Organization Credential RFC012->RFC003 - - + + RFC012->RFC006 - - + + RFC012->RFC011 - - + + RFC012->VC_EXT - - + + RFC013 - -RFC013 -Verifiable Credential IRMA Proof + +RFC013 +Verifiable Credential IRMA Proof RFC013->RFC011 - - + + RFC013->VC_EXT - - + + RFC014 - -RFC014 -Nuts Authorization Credential + +RFC014 +Nuts Authorization Credential RFC014->RFC001 - - + + RFC014->RFC003 - - + + RFC014->RFC011 - - + + RFC014->VC_EXT - - + + RFC015 - -RFC015 -Node Identity + +RFC015 +Node Identity RFC015->RFC005 - - + + RFC015->RFC006 - - + + RFC017 - -RFC017 -V2 Network Protocol + +RFC017 +V2 Network Protocol RFC015->RFC017 - - + + RFC015->DID_EXT - - + + RFC015->VC_EXT - - + + RFC017->RFC004 - - + + RFC017->RFC005 - - + + RFC017->RFC008 - - + + RFC017->RFC015 - - + + + + + +RFC019 + + +RFC019 +Employee Identity Means + + + + + +RFC019->RFC002 + + + + + +RFC019->RFC003 + + + + + +RFC019->VC_EXT + + + + + +RFC020 + + +RFC020 +Authorization Credential Extension + + + + + +RFC020->RFC014 + + + + + +RFC020->RFC019 + + diff --git a/.gitbook/source/spec-relations.dot b/.gitbook/source/spec-relations.dot index 9626242..e88dc88 100644 --- a/.gitbook/source/spec-relations.dot +++ b/.gitbook/source/spec-relations.dot @@ -20,6 +20,8 @@ digraph D { RFC014 [label = "RFC014\nNuts Authorization Credential",href = "rfc014-authorization-credential"]; RFC015 [label = "RFC015\nNode Identity",href = "rfc015-node-identity"]; RFC017 [label = "RFC017\nV2 Network Protocol",href = "rfc017-distributed-network-grpc-v2"]; + RFC019 [label = "RFC019\nEmployee Identity Means",href = "rfc019-employee-identity-means"]; + RFC020 [label = "RFC020\nAuthorization Credential Extension",href = "rfc020-authorization-credential-extension"]; } // External RFCs @@ -78,4 +80,11 @@ digraph D { RFC017 -> RFC005 RFC017 -> RFC008 RFC017 -> RFC015 + + RFC019 -> VC_EXT + RFC019 -> RFC002 + RFC019 -> RFC003 + + RFC020 -> RFC014 + RFC020 -> RFC019 } diff --git a/rfc/rfc002-authentication-token.md b/rfc/rfc002-authentication-token.md index d6e16c6..4d61b2d 100644 --- a/rfc/rfc002-authentication-token.md +++ b/rfc/rfc002-authentication-token.md @@ -140,8 +140,6 @@ This specification uses the JSON-LD format for VPs since the JWT format isn't us ## 7. Supported means -Future means will be added when available. - ### 7.1. IRMA [IRMA](https://irma.app), which stands for “I reveal my attributes” is the name of an app that implements the idemix cryptographic protocol suite. It provides strong authentication as well as privacy-preserving features such as anonymity, the ability to transact without revealing the identity of the transactor, and unlinkability, the ability of a single identity to send multiple transactions without revealing that the transactions were sent by the same identity. More information can be found on the website of the [Privacy by Design foundation](https://privacybydesign.foundation/irma-explanation/). @@ -400,4 +398,3 @@ Beside the mandatory VP fields, the following applies: * The `proof` field MUST be a singular object. * The `proof.type` field MUST equal `NutsUziSignedContract`. * The `proof.proofValue` field MUST contain the JWT in its compact serialization form as described in \[[RFC7515 section 3.1](https://tools.ietf.org/html/rfc7515#section-3.1)\]. - diff --git a/rfc/rfc019-employee-identity-means.md b/rfc/rfc019-employee-identity-means.md new file mode 100644 index 0000000..ffcb2b9 --- /dev/null +++ b/rfc/rfc019-employee-identity-means.md @@ -0,0 +1,186 @@ +# RFC019 Employee Identity Authentication Means + +| | | +|:--------------------------|:----------------| +| Nuts foundation | W.M. Slakhorst | +| Request for Comments: 019 | Nedap | +| | S. van der Vegt | +| | Nedap | +| | April 2023 | + +## Employee Identity Authentication Means + +### Abstract + +The NutsEmployeeIdentity method is an authentication _means_ which allows an organisation to assert the identity of the current user. +The organisation uses the information of the active user session to present the user with a statement about its identity and asks the user to confirm this. +After confirmation this bundle of information is signed with the organisation's private key. + +This method makes it possible to assert a user identity without the need for a personal authentication means. +This puts the organisation in the role of identity issuer instead of a trusted third party. +A use-case can choose to allow this authentication under certain (low risk) circumstances which still require a person to be authenticated in order to comply with the applicable legislation. + +This RFC is an addition to the means listed in [RFC002](./rfc002-authentication-token.md#7-supported-means) + +### Status of document + +This document is currently in draft. + +### Copyright Notice + +![](../.gitbook/assets/license.png) + +This document is released under the [Attribution-ShareAlike 4.0 International \(CC BY-SA 4.0\) license](https://creativecommons.org/licenses/by-sa/4.0/). + +## 1. Introduction + +Introducing new authentication means in an organizational setting can have quite an impact, even more when mainstream identity providers have not yet adjusted to self-sovereign identity. +New feature or applications require a higher assurance level for authentication than the current situation. +This introduces an additional authentication step in the process of users. This often happens at a place in the workflow where they don't expect it. +This is a situation that remain until the main login is adapted to the newer/higher security standard. +This RFC bridges the gap so the software can already be changed to accept newer protocols and the user can be made aware of upcoming changes without going through an authentication step using additional means. + +## 2. Terminology + +* **Client application**: The application that requires access. +* **Node**: A piece of software implementing the Nuts RFCs. +* **Resource server**: The application \(a protected resource\) that requires authorized access to its API’s. +* **VerifiableCredential**: Verifiable Credential according to the [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/). +* **VerifiablePresentation**: Verifiable Presentation according to the [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/). + +## 3. Nuts Employee Identity + +The authentication flow is as follows: + +- a user requests access to a resource that is hosted at a *resource server* and requires additional authentication. +- the *client application* starts a session on the *node* with the user data from the active session. +- the user is directed to a web page where it accepts/rejects the given conditions by pressing a button. +- this button sends the confirmation to the *node* for the given session. +- upon receiving the request, the node will issue a `NutsEmployeeCredential` from and to the organization DID associated with the existing user session. +- the credential is used to create a NutsSelfSignedPresentation. +- the VerifiablePresentation is used in the access token request as defined in [RFC003](./rfc003-oauth2-authorization.md#422-payload). + +### 3.1 User data + +In order for the resource server to comply to local legislation the following data MUST be added to the credential: + +- **Initials**: The initials of the user. +- **Family name**: The family name of the user. +- **Identifier**: A unique identifier for the user within the context of the organization. This may be an email address or an employee number. + +The user data MAY also contain a `roleName` that contains the user role within the organization. + +### 3.2 HTML based challenge + +After a session has been started by the node, the client application MUST present the user a web page that is hosted by the node. +The node MUST make sure that the web page is linked to the session and that the give user data can not be altered. +The web page MUST present the user with a dialog that explains user data will be exposed to the resource server. +The web page must clearly indicate how the user can confirm and give consent, and how the user can reject the challenge. +The session identifier used to link the user response to the session MUST be a random secure token with a minimum length of 16 bytes. +The token lifetime MUST NOT be longer than 15 minutes. + +### 3.3 VerifiableCredential + +A `NutsEmployeeCredential` is issued after the user submitted the response. This credential MUST only be used to create the verifiable presentation. +Below is an example of a `NutsEmployeeCredential`. The proof has been omitted for brevity. + +```json +{ + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json", + "https://nuts.nl/credentials/v1" + ], + "id": "did:nuts:8NYzfsndZJHh6GqzKiSBpyERrFxuX64z6tE5raa7nEjm#dde77e76-7e3c-483f-a813-2b851a6a969c", + "type": [ + "NutsEmployeeCredential", + "VerifiableCredential" + ], + "issuer": "did:nuts:8NYzfsndZJHh6GqzKiSBpyERrFxuX64z6tE5raa7nEjm", + "issuanceDate": "2023-04-20T08:52:45.941461+02:00", + "expirationDate": "2023-04-21T08:52:45.941461+02:00", + "credentialSubject": [ + { + "id": "did:nuts:8NYzfsndZJHh6GqzKiSBpyERrFxuX64z6tE5raa7nEjm", + "member": { + "identifier": "user@example.com", + "member": { + "familyName": "Tester", + "initials": "T", + "type": "Person" + }, + "roleName": "Verpleegkundige niveau 2", + "type": "EmployeeRole" + }, + "type": "Organization" + } + ], + "proof": [{...}] +} +``` + +The credential has the following requirements: + +- The type MUST contain `NutsEmployeeCredential` in addition to the default verifiable credential type. +- The `@context` MUST contain `https://nuts.nl/credentials/v1` and `https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json` in addition to the default context. +- The `issuer` and `credentialSubject.id` MUST be the same. +- The `expirationDate` MUST NOT be more than one day after the `issuanceDate`. +- `credentialSubject.type` MUST be `Organization`. +- `credentialSubject.member.type` MUST be `EmployeeRole`. +- `credentialSubject.member.member.type` MUST be `Person`. +- `credentialSubject.member.identifier` MUST contain the user identifier. +- `credentialSubject.member.member.initials` MUST contain the user initials. +- `credentialSubject.member.member.familyName` MUST contain the user family name. +- `credentialSubject.member.roleName` is optional and MAY contain the user role. +- The `proof.type` MUST be a `JsonWebSignature2020`. +- The `proof.proofPurpose` MUST be `assertionMethod`. + +### 3.4 VerifiablePresentation + +The node MUST create a verifiable presentation with the newly created credential and return it to the client application. +Below is an example of a `NutsSelfSignedPresentation`. The credential has been omitted for brevity. + +```json +{ + "@context": [ + "https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json", + "https://nuts.nl/credentials/v1", + "https://www.w3.org/2018/credentials/v1" + ], + "type": [ + "VerifiablePresentation", + "NutsSelfSignedPresentation" + ], + "verifiableCredential": [ + {...} + ], + "proof": [ + { + "challenge": "EN:PractitionerLogin:v3 I hereby declare to act on behalf of CareBears located in Caretown. This declaration is valid from Wednesday, 19 April 2023 12:20:00 until Thursday, 20 April 2023 13:20:00.", + "created": "2023-04-20T09:53:03.783007+02:00", + "expires": "2023-04-20T13:20:00+02:00", + "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il0sImtpZCI6ImRpZDpudXRzOjhOWXpmc25kWkpIaDZHcXpLaVNCcHlFUnJGeHVYNjR6NnRFNXJhYTduRWptI2JZY3VldDZFSG9qTWxhTXF3Tm9DM2M2ZXRLbFVIb0o5clJ2VXUzWktFRXcifQ..5NvfnxxZ9QT11NAYgqHybThR4Ygcd8jXjAsNy8lko3uajC-v6YiJw18a4qJEqZ7xYg3b-aBYt7UbXFbMqVlXFA", + "proofPurpose": "authentication", + "type": "JsonWebSignature2020", + "verificationMethod": "did:nuts:8NYzfsndZJHh6GqzKiSBpyERrFxuX64z6tE5raa7nEjm#bYcuet6EHojMlaMqwNoC3c6etKlUHoJ9rRvUu3ZKEEw" + } + ] +} +``` + +The presentation has the following requirements: + +- The type MUST contain `NutsSelfSignedPresentation` in addition to the default verifiable presentation type. +- The `@context` MUST contain `https://nuts.nl/credentials/v1` and `https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json` in addition to the default context. +- The `verifiableCredential` field MUST contain exactly one credential as described in the previous paragraph. +- The `challenge` MUST contain a contract as specified by [RFC002](./rfc002-authentication-token.md#5-login-contract). +- `proof.expires` MUST be filled. +- The `proof.type` MUST be a `JsonWebSignature2020`. +- The `proof.proofPurpose` MUST be `authentication`. + +## 4. Security considerations + +The _means_ is designed in a way that it is interchangeable with (other) means with a higher trust level, (using a personal authentication device). +Even it is technically possible, this means MUST NOT be used to perform machine to machine interactions which are not initiated by the current user, e.g. background jobs, fetching data automatically etc. +By doing so, a use-case can not update the trust level of a means without breaking functionality. +This means MUST only be used to claim the identity of actual and identifying natural persons working under the responsibility of the organisation, and MUST NOT identify e.g. shared accounts, teams, administrators, dummy or test users. \ No newline at end of file diff --git a/rfc/rfc020-authorization-credential-extension.md b/rfc/rfc020-authorization-credential-extension.md new file mode 100644 index 0000000..8b10ac6 --- /dev/null +++ b/rfc/rfc020-authorization-credential-extension.md @@ -0,0 +1,65 @@ +# RFC020 Authorization credential extension + +| | | +|:--------------------------|:----------------| +| Nuts foundation | W.M. Slakhorst | +| Request for Comments: 020 | Nedap | +| Amends: RFC014 | April 2023 | + +## Authorization credential extension + +### Abstract + +An `assuranceLevel` field is added to the `NutsAuthorizationCredential`. It can be used inside a `resource` to indicate the required assurance level of the authentication. + +This RFC is an addition to the means listed in [RFC014](./rfc014-authorization-credential.md) + +### Status of document + +This document is currently in draft. + +### Copyright Notice + +![](../.gitbook/assets/license.png) + +This document is released under the [Attribution-ShareAlike 4.0 International \(CC BY-SA 4.0\) license](https://creativecommons.org/licenses/by-sa/4.0/). + +## 1. Introduction + +A resource server should be able to provide information about the authentication assurance level that is used to access resources. +With the introduction of [RFC019](./rfc019-employee-identity-means.md) an authentication means with a low assurance level has been introduced. +This authentication means should not be used on resources that require a high assurance level. +An additional field in the NutsAuthorizationCredential allows a resource server to indicate which level of assurance it requires. + +## 2. Terminology + +* **Authorization server**: The application that evaluates access token requests and creates access tokens. +* **Resource server**: The application that requires authorized access to its APIs. + +## 3. AssurenceLevel field + +The additional field is called `assuranceLevel`. It MUST contain one of the following values: `low`, `substantial` or `high`. +The field is optional. When present it COULD be used by the authorization server to verify the access token request. +The field is located within a resource. A resource is located in the `resources` list. +If set, `userContext` SHOULD be `true`. If `userContext` is set to `true` and `assuranceLevel` is not set, it defaults to `low`. + +The following example shows the location of the new field, other fields have been omitted for brevity: + +```json +{ + ... + "credentialSubject": { + "id": "did:nuts:SjkuVHVqZndMVVJwcnUzbjhuZklhODB1M1M0LW9LcWY0WUs5S2", + "resources": [ + { + "path": "/DocumentReference/f2aeec97-fc0d-42bf-8ca7-0548192d4231", + "operations": ["read"], + "userContext": true, + "assuranceLevel": "low" + } + ], + "purposeOfUse": "test-service" + }, + ... +} +``` \ No newline at end of file