1 Access to data service from Happy Pets customer

In this section we describe the process of changing the PTA attribute of a packet delivery order via the packet delivery portal. The same process would be used when trying to change the PDA or delivery address.

In the following the sequences are shown for the scenario of the Happy Pets customer changing the PTA of the delivery order. In the case of the No Cheaper customer, the sequences would be the same with the only difference being that the request for changing the PTA would be denied.

1.1 General overview of component interactions

The following diagram describes the main components and general interactiosn among them, which will be described in more detail in a later section below.

• 1. The user navigates to the portal of the Service Provider using its Web Browser.

• 2. The user is not authenticated and the portal presents a QR code with the URL of the endpoint of the OIDC4VP component. The user scans the QR code and instructs the mobile to invoke the endpoint.

• 3. The SIOP/OIDC4VP authentication flow is executed between the mobile and the OIDC4VP component of the Service Provider. During the execution of the flow, both mobile and OIDC4VP component use the Verifiable Data Registry:

  • The mobile verifies that the Service Provider is in the Trusted Participant List and that the public key in that list is the one used to digitally sign the messages received from the Service Provider.

  • The Service Provider verifies that the digital signature of the Verifiable Credential presented by the user was issued by an entity which is in the Trusted Participants List.

  In addition, the Service Provider checks that the user presenting the Verifiable Credential controls the private key associated to the DID of the subject to wich the credential corresponds. In other words, that the credential was issued to the user presenting the credential.

  At the end of this flow, the OIDC4VP component notifies to the portal of the Service Provider the successful authentication, including an access token representing the claims inside the Verifiable Credential, including the roles.

• 4. The portal refreshes the screen presenting the available services to the user. The access token is sent to the browser so it can be used as a Bearer token in the Authorization header of subsequent requests.

• 5. The user clicks a button invoking a service that requires authorization. The request is intercepted by the plugin of the PEP proxy, which invokes the PDP (Policy Decision Point) to get a decission on whether authorize the request or not.

• 6. The PDP uses the data in the incoming request (including the claims inside the access token) to query the Authorization Registry for the appropriate policy rules. The PDP evaluates the rules to make a decision.

• 7. The PDP returns the successful decission to the pluging of the PEP, which then forwards the request to the original target (in this case the Context Broker).

• 8. The Context Broker executes the request and sends the reply back, will is presented to the user in the web browser.

1.2 Sequence description (Happy Pets Customer)

The following gives a detailed description of the process of changing the PTA attribute by the Happy Pets customer, when using Verifiable Credentials.

In the interactions, Packet Delivery acts as a Relying Party (RP). The actual Trust Framework used in a real implementation will determine the DID associated to all the participants, but for this example we assume that the DID of Packet Delivery is did:elsi:packetdelivery. Additionally, Packet Delivery performs signatures using a private key associated to its DID and registered publicly in the Trust Framework (e.g., in the Trusted Participants List). The identification of the corresponding public key for signature verification in this example is did:elsi:packetdelivery#key-verification, where key-verification identifies the specific key used in a signature if the entity has several keys registered in the Trust Framework.

The description of the above diagram is the following:

• 1. Happy Pets customer directs her browser to access the Packet Delivery company portal.

• 2. The browser sends a request to the Packet Delivery portal server.

• 3. Happy Pets customer gets forwarded to a page for selecting the desired Identity Provider for login. One of the login options is “Login with Verifiable Credentials” or something similar.

• 4. Happy Pets customer selects the “Verifiable Credentials” login method, which causes the Packet delivery company portal to generate a QR containing inside the URL of the /authentication-requests endpoint of the RP (Relying Party) component of Packet Delivery. A QR code is used because a Self-Issued OP may be running locally as a native application or progressive web application (PWA), the RP may not have a network-addressable endpoint to communicate directly with the OP. We have to leverage the implicit flow of OpenID Connect to communicate with such locally-running Ops, as described in [SIOPv2].

  The QR code includes a nonce called state that will be used later by the portal to know when a specific login session has finished. In our use case, the URL inside the QR could look like this:

  GET /authentication-requests?state=af0ifjsldkj HTTP/1.1
  Host: rp.packetdelivery.com

• 5. The QR code is displayed in the customer browser with instructions to scan it and go to the URL inside it.

• 6. The customer scans the QR with her mobile and tells the mobile to go to the URL in the QR.

• 7. The mobile performs a GET request to the url inside the QR (e.g. https://www.packetdelivery.com/api/authentication-requests). This starts a standard SIOP (Self-Issued OpenID Provider) flow, where the Packet Delivery company plays the role of Relying Party (RP in Open ID Connect terminology) and the mobile device of the customer as a Self-Issued IDP (SIOP).

• 8. Packet Delivery company RP creates a SIOP Authentication Request. The parameters comprising a request for verifiable presentations are given in section 5 of [OIDC4VP] and in section 10.1 of [SIOPv2] and are reproduced here with the particularities of this use case, in particular that this is a cross-device interaction:

  • response_type. REQUIRED. Must be "vp_token". This parameter is defined in [RFC6749]. The possible values are determined by the response type registry established by [RFC6749]. The [OIDC4VP] specification introduces the response type "vp_token". This response type asks the SIOP to return only a VP Token in the Authorization Response, which is what we want in our case.

  • scope. REQUIRED. This parameter is defined in [RFC6749] which allows it to be used by verifiers to request presentation of credentials by utilizing a pre-defined scope value designating the type of credential. See section Request Scope for more details. We use in this instance the value gaiax.credentials.presentation.CustomerCredential which means that the RP (PacketDelivery) is asking the SIOP (customer wallet) to send a credential of type CustomerCredential issued by any participant in the ecosystem.

  • response_mode. REQUIRED. MUST be “post”. As this is a cross-device scenario, this response mode is used to request the Self-Issued OP to deliver the result of the authentication process to a certain endpoint using the HTTP POST method. This endpoint to which the SIOP shall deliver the authentication result is conveyed in the parameter redirect_uri.

  • redirect_uri. (REQUIRED). MUST be a valid RP endpoint. The Authentication Response is sent to this endpoint using POST and encoding application/json)

  • client_id. REQUIRED. MUST be the DID of the RP (Packet Delivery in this case) so it can be resolved by the SIOP and checked against a Trusted List, or rejected if it does not pass validation. This provides a high level of assurance to the SIOP that the RP is really who it claims.

  • nonce. REQUIRED. This parameter follows the definition given in [OpenID.Core]. It is used to securely bind the verifiable presentation(s) provided by the wallet (SIOP) to the particular transaction managed by the RP.

  • state. REQUIRED. Used by the portal component of Packet Delivery to associate the start of an authentication session with the end of that session when the RP component notifies to the portal.

  • presentation_definition. CONDITIONAL. A string containing a presentation_definition JSON object as defined in Section 4 of [DIF.PresentationExchange]. We do not use this parameter because scope already specifies the credential type.

  • presentation_definition_uri. CONDITIONAL. A string containing a URL pointing to a resource where a presentation_definition JSON object as defined in Section 4 of [DIF.PresentationExchange] can be retrieved. We do not use this parameter because scope already specifies the credential type.

  Note: A request MUST contain either a presentation_definition or a presentation_definition_uri or a single scope value representing a presentation definition, those three ways to request credential presentation are mutually exclusive. We use here the scope mechanism.

  This is an example request (with newlines and leading spaces added for legibility):

  openid://?
     scope=gaiax.credentials.presentation.CustomerCredential
     &response_type=vp_token
     &response_mode=post
     &client_id=did:elsi:packetdelivery
     &redirect_uri=https%3A%2F%2Fwww.packetdelivery.com%2Fapi%2Fsiop/authentication_response%2Fcb
     &state=af0ifjsldkj
     &nonce=n-0S6_WzA2Mj

• 9. The SIOP Authentication Request is returned to the mobile in the reply body of the GET request, as a JWT in JWS form (), signed with the public key associated with the DID in the client_id field of the Authorization Request. The JWT MUST be generated according to the best practices described in [RFC8725]. This is an example of the unencoded contents of such JWT:

  --------------- Header ---------------
  {
     "alg": "ES256",      // This should be one of the supported algorithms in the Data Space
     "kid": did:elsi:packetdelivery#key-verification
     "typ": "JWT"
  }
  --------------- Payload ---------------
  {
     "iss": did:elsi:packetdelivery,     // Should correspond with the client_id in the AR
     "iat": 1667194901,
     "exp": 1667194961,                  // To avoid replays, here it expires in 60 secs
     "auth_request": "openid://?scope=...&response_type=vp_token&...",
  }

  Where the claim iss MUST be the DID of the RP (in this case Packet Delivery) and correspond exactly with the client_id parameter in the Authentication Request. The claim auth_request contains the Authentication Request as a string. The expiration time in claim exp avoids replays and can be very short because it is used by the SIOP just on reception of the Authentication Request.

• 10. In this and steps 11 and 12 the customer SIOP verifies that the RP (in this case Packet Delivery) is a trusted entity belonging to the ecosystem, by resolving the DID of the RP received in the client_id parameter of the Authentication Request and verifying the signature of the JWT.

  Before starting DID resolution, we perform the standard verification of the JWT as described in [RFC8725] and [RFC7515], except for the signature. We also check for the existence of the claim auth_request in the JWT and that its contents are a well-formed Authentication Request.

  In addition, we get the DID of the RP from the client_id parameter of the Authentication Request received in the JWT, making sure that it corresponds exactly to the iss claim in the payload of the JWT.

  We resolve that DID by sending a GET request to the /api/did/v1/identifiers/{did} endpoint of one of the Universal Resolvers in the ecosystem, where {did} should be the DID of the RP retrieved in the previous step (in our case the DID of Packet Delivery). The endpoint returns the DID Document corresponding to the DID of the RP.

• 11. The DID Document (as per W3C) contains relevant information about the entity owning the DID, in particular:

  • The Public Key of the entity used to verify its digital signatures

  • Status of the entity in the Trusted Participant List

  The DID Document is extensible, and can contain any additional public information which may be relevant for the use case, like commercial name of the RP, website address, contact information, etc.

  An example DID Document (in this example stored in the Alastria RedT blockchain network) is:

  {
     "payload": {
        "@context": [
           "https://www.w3.org/ns/did/v1",
           "https://w3id.org/security/v1"
        ],
        "id": "did:elsi:packetdelivery",
        "verificationMethod": [
           {
           "id": "did:elsi:packetdelivery#key-verification",
           "type": "JwsVerificationKey2020",
           "controller": "did:elsi:packetdelivery",
           "publicKeyJwk": {
           "kid": "key-verification",
           "kty": "EC",
           "crv": "secp256k1",
           "x": "V8XptJkb5wplYkExcTF4nkyYVp7t5H5d5C4UPqCCM9c",
           "y": "kn3nSPxIIvd9iaG0N4v14ceuo8E4PcLXhhGeDzCE7VM"
           }
           }
        ],
        "service": [
           {
           "id": "did:elsi:packetdelivery#info",
           "type": "EntityCommercialInfo",
           "serviceEndpoint": "https://www.packetdelivery.com/info",
           "name": "Packet Delivery co."
           },
           {
           "id": "did:elsi:packetdelivery#sms",
           "type": "SecureMessagingService",
           "serviceEndpoint": "https://www.packetdelivery.com/api/securemessage"
           }
        ],
        "anchors": [
           {
           "id": "redt.alastria",
           "resolution": "UniversalResolver",
           "domain": "packetdelivery.ala",
           "ethereumAddress": "0xbcB9b29eeb28f36fd84f1CfF98C3F1887D831d78"
           }
        ],
        "created": "2021-11-14T13:02:37Z",
        "updated": "2021-11-14T13:02:37Z"
     }
  }

  The resolution process is implemented as follows:

  1. Perform the standard verification of the JWT as described in [RFC8725] and [RFC7515], except for the signature.

  2. Check for the existence of the claim auth_request in the JWT and that its contents are a well-formed Authentication Request.

  3. Get the DID of the RP from the client_id parameter of the Authentication Request received in the JWT, making sure that it corresponds exactly to the iss claim in the payload of the JWT.

  4. Send a GET request to the /api/did/v1/identifiers/{did} endpoint of one of the Universal Resolvers in the ecosystem, where {did} should be the DID of the RP retrieved in the previous step (in our case the DID of Packet Delivery). The endpoint returns the DID Document corresponding to the DID of the RP.

  5. Perform the standard verifications on the DID Document as described in [VC_DATA]. In particular it is important to check that the DID inside the DID Document corresponds with the DID that was specified in the GET request.

  The Universal Resolver server used in this step has to be operated by an entity which is trusted by the customer. To minimize the required trust in the ecosystem there may be many Universal Resolver servers operated by different entities. At least one of those trusted entities has to be configured in the wallet of the user.

  The underlying Trusted Lists queried by the Universal Resolver can be implemented with any technology suitable for the ecosysmen. In this implementation FIWARE uses a Universal Resolver accessing a blockchain network with a Public-Permissioned model, where the Trusted Lists are managed

• 12. After DID resolution, we need to check the signature of the JWT containing the Authorization Request.

  As mentioned above, the DID Document includes one or more public keys inside the verificationMethod array. The keys are identified by the id field in each element of the array. The customer wallet uses the kid field that was received in the Authentication Request (in the protected header of the JWT) to select the corresponding Public Key and verify the signature of the JWT. It also verifies that the top-level id field in the DID Document (did:elsi:EU.EORI.NLPACKETDEL) is equal to the client_id parameter of the Authentication Request.

• 13. The customer wallet creates an Authentication Response to be posted in the redirect_uri specified by Packet Delivery company in step 8. The contents of the Authentication Response are described below.

  The response is constructed as defined in section 6.1 of [OIDC4VP]. In particular, because the Authorization Request included only vp_token as the response_type, the VP Token is provided directly in the Authorization Response and a separate id_token is not needed.

  The contents of the Authentication Response in our specific use case are (shown here with the POST parameters needed to send it):

  POST /api/siop/authentication_response/cb HTTP/1.1
  Host: www.packetdelivery.com
  Content-Type: application/x-www-form-urlencoded
  
  presentation_submission=[see definition below]
  &vp_token=[see definition below]

  The content of the presentation_submission parameter in the above Authentication Request is:

  {
     "definition_id": "CustomerPresentationDefinition",
     "id": "CustomerPresentationSubmission",
     "descriptor_map": [
        {
           "id": "id_credential",
           "path": "$",
           "format": "ldp_vp",
           "path_nested": {
              "format": "ldp_vc",
              "path": "$.verifiableCredential[0]"
           }
        }
     ]
  }

  Which complies with [DIF.PresentationExchange] and refers to the VP in the vp_token parameter provided in the same response, which looks as follows:

  {
     "@context": [
        "https://www.w3.org/2018/credentials/v1"
     ],
     "type": [
        "VerifiablePresentation"
     ],
     "verifiableCredential": [
        {
           "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://happypets.fiware.io/2022/credentials/employee/v1"
           ],
           "id": "https://happypets.fiware.io/credentials/25159389-8dd17b796ac0",
           "type": [
              "VerifiableCredential",
              "CustomerCredential"
           ],
           "issuer": {
              "id": "did:elsi:happypets"
           },
           "issuanceDate": "2022-03-22T14:00:00Z",
           "validFrom": "2022-03-22T14:00:00Z",
           "expirationDate": "2023-03-22T14:00:00Z",
           "credentialSubject": {
              "id": "did:peer:99ab5bca41bb45b78d242a46f0157b7d",
              "verificationMethod": [
                 {
                    "id": "did:peer:99ab5bca41bb45b78d242a46f0157b7d#key1",
                    "type": "JwsVerificationKey2020",
                    "controller": "did:peer:99ab5bca41bb45b78d242a46f0157b7d",
                    "publicKeyJwk": {
                       "kid": "key1",
                       "kty": "EC",
                       "crv": "P-256",
                       "x": "lJtvoA5_XptBvcfcrvtGCvXd9bLymmfBSSdNJf5mogo",
                       "y": "fSc4gZX2R3QKKfHvS3m2vGSVSN8Xc04qsquyfEM55Z0"
                    }
                 }
              ],
              "roles": [
                 {
                    "target": "did:elsi:packetdelivery",
                    "names": [
                       "P.Info.gold"
                    ]
                 }
              ],
              "name": "Jane Doe",
              "given_name": "Jane",
              "family_name": "Doe",
              "preferred_username": "j.doe",
              "email": "janedoe@packetdelivery.com"
           }
        }
     ]
  }

  The above Verifiable Presentation includes only one Verifiable Credential of type CustomerCredential that was issued by Happy Pets to a customer. The credentialSubject object in the credential has an id field with value did:peer:99ab5bca41bb45b78d242a46f0157b7d which is the DID of the user and that is not registered in any blockchain or centralized repository.

• 14. The SIOP (customer wallet) sends the Authentication Response to the endpoint passed in the redirect_uri parameter of the Authentication Request, sending a HTTP POST request using application/x-www-form-urlencoded encoding.

• 15 and 16. The Packet Delivery RP component receives the Authorization Request and has to perform verifications, the standard ones being defined in [DIF.PresentationExchange]. In order to verify that the Verifiable Credential has been issuer by a trusted participant in the ecosystem, Packet Delivery has to verify:

  1. That the DID of the entity which is the issuer of the VC is a trusted participant.

  2. That the VC was digitally signed by that participant.

  Both verifications can be done by performing DID resolution, checking that the resulting DID Document contains the public key corresponding to the one specified in the Verifiable Credential, and by verifying the digital signature of the credential against that public key.

  The process for DID resolution and getting the public key from the resulting DID Document is exactly the same as the one described in steps 10 and 11 before.

  Resolution is performed sending a GET request to a server implementing the Universal Resolver API with the DID of the issuer of the Verifiable Credential. In our case the DID is the value of the field verifiableCredential[0].issuer.id which is the DID of Happy Pets: did:elsi:happypets. Packet Delivery could use a Universal Resolver server operated by a different entity, but this would reduce the level of trust compared to using its own server, which is the recommended setup.

• 17. After verifying the credential, Packet Delivery can also verify that the Verifiable Presentation including the Verifiable Credential is sent by the customer and not by a malicious agent. To do so, it uses the Public Key of the customer in the verificationMethod of the credentialSubject structure. That public key is cryptographically bound to the customer DID during the onboarding process that Happy Pets performed with the customer.

• 18. The RP component of Packet Delivery company creates an Access Token for the customer so she can use it to access services in Packet Delivery company in the future. The RP component generates an Access Token in JWT format signed by the RP component. The access token is intended for use as bearer token over HTTP/1.1 [RFC2616] using Transport Layer Security (TLS) [RFC5246] to access protected resources, and it should use the JWT Profile profile described in [RFC9068].

  For our use case, the JWT access token looks like:

  Header:
  
  {"typ":"at+JWT","alg":"RS256","kid":"at-key"}
  
  Claims:
  
  {
     "iss": "did:elsi:packetdelivery",
     "sub": "did:peer:99ab5bca41bb45b78d242a46f0157b7d",
     "aud":   "https://contextbroker.packetdelivery.com/",
     "exp": 1639528912,
     "iat": 1618354090,
     "jti" : "dbe39bf3a3ba4238a513f51d6e1691c4",
     "client_id": "did:elsi:packetdelivery",
     "scope": "vp_token",
     "verifiableCredential": [the VC that was received inside the Verifiable Presentation]
  }

  Where, according to [RFC9068]:

  • iss and client_id have the same value because the access token has been generated by the RP component of Packet Delivery, not by an IdP as in the "classic" OIDC flows.

  • sub identifies the customer using the DID inside the Verifiable Credential received

  • aud identifies the RS (Resource Server) component in Packet Delivery. In this case we assume that it is internal and does not have a DID assigned, so we use the URI of the component.

  • kid in the header identifies the key that is used to sign the JWT and which must be configured up-front and known by the RS (Resource Server.

  • scope has the same value as the equivalent scope parameter in the initial Authorization Request.

  • verifiableCredential contains the Verifiable Credential that was received, specifically the value of the first element of the field verifiableCredential of the Verifiable Presentation.

• 19. The RP component of Packet Delivery sends a successful response to the POST request that the SIOP (customer wallet) used to send the Authorization Request to the RP. The wallet receives the response to the POST indicating the success or failure of the process. The RP component of Packet Delivery continues processing because the web portal of Packet Delivery has to be refreshed with the services that this specific customer can access, based on the information received in the Verifiable Credential and the access control policies implemented by Packet Delivery.

• 20. The RP component of Packet Delivery notifies the Portal to refresh the login page so it can present the services to the customer. The notification includes the following:

  1. The state nonce that was generated by the portal when it generated the QR code. The portal uses the state nonce to know what login session is notified.

  2. The access token generated before.

  The notification is a simple POST request with both parameters in the body:

  POST /api/notify HTTP/1.1
  Host: portal.packetdelivery.com
  Content-Type: application/x-www-form-urlencoded
  
  access_token=[the access token]
  &state=af0ifjsldkj

  The portal component replies immediately and continues processing.

• 21. The Packet Delivery portal refreshes the screen and displays the services available to customers, sending the Access Token to the browser of the customer.

• 22. The customer selects the option "Change PTA on delivery order" and the browsers sends a GET request to the Packet Delivery portal, including the Access Token as a Bearer token in the Authorization header of the HTTP request. For example:

  GET /resource HTTP/1.1
  Host: contextbroker.example.com
  Authorization: Bearer [the access token]

  The request is intercepted by the Policy Enforcement Point (PEP) component of Packet Delivery, an API gateway.

• 23. The PEP checks that the request to the protected resource includes an Authorization header with a Bearer token, digitally signed by the RP component of Packet Delivery with one of the keys previously configured in the API gateway.

  The way to do this depends on the implementation of the PEP but if it is based on Nginx, an example configuration looks like:

  location = /auth {
     proxy_pass [internal address of PDP component]
     proxy_pass_request_body off;
     proxy_set_header Content-Length "";
     proxy_set_header X-Original-URI $request_uri;
  }
  
  location /[external path of Resource Server] {
     auth_request /auth;
     proxy_pass [internal address of Resource Server]
  }

  The PDP will receive the original request without the body but with the headers, which include the Authotization header with the Access Token. If the PDP returns a 2xx response code, the access is allowed by the PEP. If it returns 401 or 403, the access is denied with the corresponding error code. Any other response code returned by the PDP is considered an error. For the 401 error, the client also receives the “WWW-Authenticate” header from the subrequest response.

• 24. As described in the previous step, the PEP asks the Policy Decision Point (PDP) to evaluate if the Access Token authorizes the caller to access the target service ("Change PTA on delivery order"). It forwards the original request including the Access Token to the PDP.

• 25 and 26. The PDP uses information in the Access Token to retrieve from the Policy Retrieval Point (PRP)the relevant policy definitions required to evaluate authorization for the request. The PRP is where the access authorization policies are stored, typically a database or the filesystem.

• 27. The PDP uses information in the Access Token and the policies retrieved from the PRP to evaluate policies associated to customer roles and any additional attributes in the token. One of the policies retrieved correwsponds to the purchasing status of the Happy Pets company with respect to the services provided by Packet Delivery.

• 28. In our use case, the customer is of category Gold and Packet Delivery is currently paying for the Gold service so the evaluation of the policies grants access to the requested service ("Change PTA on delivery order"), by returning a 2xx response code. If it returns 401 or 403, the access is denied.

• 29. The PEP (API gateway) receives the successful reply and forwards the request, including the Access Token, to the RS (Resource Server). In this case to the Context Broker, not shown in the diagram.

• 30 and 31. The request is executed and the reply is sent to the customer browser, where the customer can continue using the Packet Delivery portal for any other requests she may want to execute.

{
   "id": "EmployeePresentationDefinition",
   "input_descriptors": [
      {
         "id": "employee credential",
         "format": {
            "ldp_vc": {
               "proof_type": [
                  "Ed25519Signature2018"
               ]
            }
         },
         "constraints": {
            "fields": [
               {
                  "path": [
                     "$.type"
                  ],
                  "filter": {
                     "type": "string",
                     "pattern": "EmployeeCredential"
                  }
               }
            ]
         }
      }
   ]
}

{
   "id": "CustomerPresentationDefinition",
   "input_descriptors": [
      {
         "id": "customer credential",
         "format": {
            "ldp_vc": {
               "proof_type": [
                  "Ed25519Signature2018"
               ]
            }
         },
         "constraints": {
            "fields": [
               {
                  "path": [
                     "$.type"
                  ],
                  "filter": {
                     "type": "string",
                     "pattern": "CustomerCredential"
                  }
               }
            ]
         }
      }
   ]
}