This specification describes an application of Verifiable Credentials for use as Authorization Capabilities.

This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.

Please open an issue , if you wish to collaborate on this specification.

You may also reach out via the mailing list: public-credentials@w3.org (subscribe, archives)

Introduction

Traditional mechanisms for defining, requesting and granting authorization are brittle, outdated, and lack the semantic expressiveness to account for the scope and scale of modern software applications, and the privacy concerns of data subjects and controllers.

This specification describes an application of [[vc-data-model]] for the purpose of granting, invoking and verifying authorization capabilities.

This work is inspired by [[ZCAP-LD]], [[GNAP]] and the challenges.

Terminology

Verifiable Credential

See [[vc-data-model]].

Verifiable Presentation

See [[vc-data-model]].

Authorization Capability

A Verifiable Credential definining the authorization assigned by an issuer to a subject.

Capability Invocation

A Verifiable Presentation of one or more AuthorizationCapability Verifiable Credentials.

Authorization

Requesting

Define relationship to GNAP / CHAPI.

Granting

An authorization capability is created by issuing an AuthorizationCapability Verifiable Credential to one or more subjects. 

          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/v2"
            ],
            "id": "http://example.com/zcaps/0",
            "type": [
              "VerifiableCredential"
            ],
            "issuer": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV",
            "issuanceDate": "2020-03-10T04:24:12.164Z",
            "name": "Manage Vault Documents",
            "description": "This capability grants a subject the ability to manage documents in a confidential datastore.",
            "credentialSubject": {
              "id": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV",
              "type": "AuthorizationCapability",
              "authorization": [
                {
                  "type": "https://w3id.org/security#capabilityInvocation",
                  "locations": [
                    "https://example.com/edvs/123"
                  ],
                  "actions": [
                    "https://w3id.org/security#vault.document.create",
                    "https://w3id.org/security#vault.document.read",
                    "https://w3id.org/security#vault.document.update",
                    "https://w3id.org/security#vault.document.delete"
                  ]
                }
              ]
            },
            "proof": {
              "type": "JsonWebSignature2020",
              "created": "2020-12-19T22:02:43.521Z",
              "jws": "eyJhbGciOiJFUzM4NCIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..ij41tt92XHl_USxr_ICLODJDFAr9-PhWjdP-nj8g1hXyJ-tCH4joR8nAeKQsFZWZXZhiUAakzxGVILjkHc_Xihm1DuQ3fLgxBl8RbkqXodLRjx6qzP3UQsghkk0Pts6n",
              "proofPurpose": "assertionMethod",
              "verificationMethod": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV#zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV"
            }
          }

Delegating

An authorization capability is delegated by issuing an AuthorizationCapability verifiable credential to one or more subjects. 

          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/v2"
            ],
            "id": "http://example.com/zcaps/1",
            "type": [
              "VerifiableCredential"
            ],
            "issuer": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV",
            "issuanceDate": "2020-03-10T04:24:12.164Z",
            "name": "Read Vault Documents",
            "description": "This capability grants a subject the ability to read documents in a confidential datastore.",
            "credentialSubject": {
              "id": "did:key:zACHdHPDvB6e4as9JB7xNnTydJyhUTNv4qFGfUj8mGRY3ezJh21927ZhNDw47KqeRMjNNFwGGU8uac7QoTmDBXPcXWRXW9J5MWLJxc9GwshoC6CT6ekEX6phS319LVuvPWY4mc39",
              "type": "AuthorizationCapability",
              "authorization": [
                {
                  "capability": "http://example.com/zcaps/0",
                  "caveat": [
                    {
                      "actions": [
                        "https://w3id.org/security#vault.document.read"
                      ]
                    }
                  ]
                }
              ]
            },
            "proof": {
              "type": "JsonWebSignature2020",
              "created": "2020-12-19T22:14:33.784Z",
              "jws": "eyJhbGciOiJFUzM4NCIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..qS5Xg8I2ktyVMmgE8V5pLbnQPpK13n0XwSyF6FERKfIpn9CylWpKyy-vh123Gg8YI31GzFMHkD2AUgd1ZdQGHRIPTvztw3VAx4T6_SOyH_wPKI2f3SiDXGlSejwhXvEy",
              "proofPurpose": "assertionMethod",
              "verificationMethod": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV#zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV"
            }
          }

Invoking

An authorization capability is invoked by presenting an CapabilityInvocation verifiable presentation containing one or more AuthorizationCapability Verifiable Credentials. 

          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/v2"
            ],
            "type": [
              "VerifiablePresentation",
              "AuthorizationCapabilityInvocation"
            ],
            "verifiableCredential": [
              {
                "@context": [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/v2"
                ],
                "id": "http://example.com/zcaps/1",
                "type": [
                  "VerifiableCredential"
                ],
                "issuer": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV",
                "issuanceDate": "2020-03-10T04:24:12.164Z",
                "name": "Read Vault Documents",
                "description": "This capability grants a subject the ability to read documents in a confidential datastore.",
                "credentialSubject": {
                  "id": "did:key:zACHdHPDvB6e4as9JB7xNnTydJyhUTNv4qFGfUj8mGRY3ezJh21927ZhNDw47KqeRMjNNFwGGU8uac7QoTmDBXPcXWRXW9J5MWLJxc9GwshoC6CT6ekEX6phS319LVuvPWY4mc39",
                  "type": "AuthorizationCapability",
                  "authorization": [
                    {
                      "capability": "http://example.com/zcaps/0",
                      "caveat": [
                        {
                          "actions": [
                            "https://w3id.org/security#vault.document.read"
                          ]
                        }
                      ]
                    }
                  ]
                },
                "proof": {
                  "type": "JsonWebSignature2020",
                  "created": "2020-12-19T22:14:33.784Z",
                  "jws": "eyJhbGciOiJFUzM4NCIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..qS5Xg8I2ktyVMmgE8V5pLbnQPpK13n0XwSyF6FERKfIpn9CylWpKyy-vh123Gg8YI31GzFMHkD2AUgd1ZdQGHRIPTvztw3VAx4T6_SOyH_wPKI2f3SiDXGlSejwhXvEy",
                  "proofPurpose": "assertionMethod",
                  "verificationMethod": "did:key:zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV#zACHcxDJnZZXpzEs2fMkCctJPmgccBHM9rCQVQrkRS5Dkesdz94Xj7EEKs8vJ95prX76ZhFcT73jiYf4r7ynZZciLgAgkfMVUpsZC2Sykdt7GLv3WFbMopmgiJJQEami568r5iBV"
                }
              }
            ],
            "holder": "did:key:zACHdHPDvB6e4as9JB7xNnTydJyhUTNv4qFGfUj8mGRY3ezJh21927ZhNDw47KqeRMjNNFwGGU8uac7QoTmDBXPcXWRXW9J5MWLJxc9GwshoC6CT6ekEX6phS319LVuvPWY4mc39",
            "proof": {
              "type": "JsonWebSignature2020",
              "created": "2020-12-19T22:14:33.893Z",
              "challenge": "123",
              "jws": "eyJhbGciOiJFUzM4NCIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..wB7OKxgt5FW1opChzemnm0YfL7S3B97VdsHrn1ohLSi6er1Fo8-nBzeyORCgEc2BWpo-bKJ1kTa5SMGtA9RRMCAKKG1pejOHMMuomDjTTggBbI3DBpS45LX2sxVpLJV7",
              "proofPurpose": "authentication",
              "verificationMethod": "did:key:zACHdHPDvB6e4as9JB7xNnTydJyhUTNv4qFGfUj8mGRY3ezJh21927ZhNDw47KqeRMjNNFwGGU8uac7QoTmDBXPcXWRXW9J5MWLJxc9GwshoC6CT6ekEX6phS319LVuvPWY4mc39#zACHdHPDvB6e4as9JB7xNnTydJyhUTNv4qFGfUj8mGRY3ezJh21927ZhNDw47KqeRMjNNFwGGU8uac7QoTmDBXPcXWRXW9J5MWLJxc9GwshoC6CT6ekEX6phS319LVuvPWY4mc39"
            }
          }

Verification

Verification of capabilities and invocations mirrors the process of verifiying credentials and presentations, but with some notable exceptions, to support delegation and revocation.

In order to verify a capability invocation, both the inovcation and the associated capability chain must be verified, similar to how a verifiable presentation is only verified when the credentials and the presentation have been verified.

Capability Chain

In order to verify a capability, a verifier must traverse backwards from a leaf capability to a root capability.

Each capability can be embedded by value or by reference (uri).

If any capability is not resolvable, or if verification fails, the capability chain verification process must exit immediatly, and the chain MUST be considerd to have failed verification.

Capability Invocation

In order to verify a capability invocation, the associated capability chain must be verified as a series of linked verifiable credentials.

After the capability chain has been verified, the capability invocation MUST be verified, as a verifiable presentation.

If either the capability chain or the capability invocation verification fails, the invocation MUST be considerd to have failed verification.

Privacy Considerations

This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.

Security Considerations

There are a number of security considerations that implementers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.

While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.

Accessibility Considerations

There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.

This section details the general accessibility considerations to take into account when utilizing this data model.

Internationalization Considerations

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.