vc_change_pta.puml

@startuml vc_change_pta

title Packet Delivery - HappyPets customer changes PTA

autonumber 1
skinparam SequenceBoxBorderColor transparent

database "Universal\nResolver" as DIDR

box User #MistyRose
    actor "Prime Customer" as primeCustomer #f7a6a6
    participant "Customer\nSIOP" as customerSIOP #f7a6a6
    participant "Customer\nBrowser" as customerBrowser #f7a6a6
endbox

box PacketDelivery #ebfcef
    boundary "Packet Delivery\nPEP" as packetDeliveryPEP #92e8c6
    participant "Packet Delivery\nRP" as packetDeliverySIOP #92e8c6
    database "Packet Delivery\nUniversal\nResolver" as DIDR_pack #92e8c6
    participant "Packet Delivery\nPortal" as packetDeliveryPortal #92e8c6
    participant "Packet Delivery\nPDP" as packetDeliveryPDP #92e8c6
    participant "Packet Delivery\nAuthorisation\nRegistry" as packetDeliveryAR #92e8c6
endbox

'Visit the Packet Delivery Portal and select logon method
primeCustomer-->customerBrowser ++: Access portal
customerBrowser->packetDeliveryPortal --++: Accesses portal
packetDeliveryPortal->customerBrowser --++: Please select login method

group Authentication

    'A QR code is displayed and scanned by the customer to start the login process.
    'The QR code includes the URL of th eendpoint that will start the process when invoked by the SIOP
    customerBrowser->packetDeliveryPortal --++: Select "Login with VC"
    note right customerBrowser
        When customer selects "Login with Verifiable Credential"
        the Packet Delivery Portal displays a QR.
        The QR includes a nonce called <state> that
        will be used by Packet Delivery system to match the
        start with the end of the login process
    end note
    packetDeliveryPortal->customerBrowser --++: Display QR including endpoint URL + <state>
    customerBrowser-->customerSIOP --++: Scan QR

    'Perform a GET to start the process
    note over customerSIOP
        The customer uses its wallet to scan the QR in Packet Delivery Portal
        The wallet uses the URL inside the QR to start the process
    end note
    customerSIOP -> packetDeliverySIOP ++:GET /authentication-requests

    note over packetDeliverySIOP: The SIOP authentication process is started
    packetDeliverySIOP -> packetDeliverySIOP :Create\nAuthenticaton Request
    return URI + <Request Token>
    note right customerSIOP
        The Request Token contains the DID of Packet Delivery, among other things
        The URI is the standard SIOP URI for callback
    end note

    'Resolve the DID of Packet Delivery
    customerSIOP -> DIDR ++: Resolve DID of\nPacket Delivery in\n**Trusted Participant List**
    note right DIDR
        This is a Universal Resolver server, that receives a DID and resolves it to a DID Document.
        The DID Document (as per W3C) contains relevant information about the entity owning the DID,
        containing:
        - The Public Key of the entity used to verify its digital signature
        - Status of the entity in the Trusted Participant List

        The DID Document is extensible, and can contain any public information which may be relevant for the use case.
        The Universal Resolver server has to be operated by a trusted entity for the customer and for minimizing the
        required trust in the ecosystem there may be as many nodes as needed operated by different entities.
        At least one of those trusted entities has to be configured in the wallet of the user.
        FIWARE uses a Universal Resolver accessing a blockchain network where the Trusted Lists are managed, but Trusted Lists
        can be implemented with any technology suitable for the ecosysmen.
    end note 
    return **DID Document** of\nPacket Delivery Co

    'Verify the Authentication Request using the DID Document
    customerSIOP -> customerSIOP: Verify Authentication Request
    note right customerSIOP
        The wallet checks:
        - the digital signature of the Authentication Request
        - that the DID inside the request matches the DID inside the DID Document from Universal Resolver
        - any additional info inside the request against the DID Document, as required by the use case

        Now the wallet knows that Packet Delivery Co is a
        trusted participant entity and that it signed the request and the request has not been modified
        since it was signed.
    end note
    customerSIOP -> customerSIOP: Create Authentication Response\nwith <vp_token>

    note right customerSIOP
        The wallet creates a SIOP Authentication Response
        The vp_token includes one or more Verifiable Credentials
        In this case there is only one Verifiable Credential, issued
        by Happy Pets to its customer
    end note
    'Perform a POST to send the Authentication Response
    customerSIOP -> packetDeliverySIOP --++: POST <Authentication Response> /siop-sessions

    note right customerSIOP
        The URI to which the POST is done was specified in the
        Authentication Request that was received by the wallet
    end note

    'Resolve DID of HappyPets to see if it is trusted issuer
    packetDeliverySIOP->DIDR_pack ++: Resolve DID of\nHappy Pets in\n**Trusted Participant List**
    note left DIDR_pack
        This can be a Universal Resolver operated by Packet Delivery Co or by any entity trusted by it.
        For maximum level of trust, the node is operated by Packet Delivery.
        The Verifiable Credential received from the user was signed by Happy Pets and
        includes the DID of Happy Pets.
        Packet Delivery retrieves the DID Document for that DID to check that it is a trusted participant entity.
        In addition it checks the digital signature using the Public Key inside the DID Document.
    end note
    return **DID Document**\nwith public key

    'Verify the Authentication Response from the mobile wallet
    packetDeliverySIOP->packetDeliverySIOP: Verify\nAuthentication Response
    note over packetDeliverySIOP
        The VC issued by Happy Pets to the customer includes the Public Key associated to the customer
        and that was used to sign the Authentication Response.
        The Public Key of the customer was verified when the customer was onboarded by Happy Pets.
        For maximum privacy, SIOP (customer) can have a different key for each company where she is a customer.
        In each onboarding process the SIOP can generate a different key pair (pairwise DIDs).
    end note
 
    'Generate an Access Token including the information in the Verifiable Credential
    packetDeliverySIOP->packetDeliverySIOP : Generate Access Token
    note over packetDeliverySIOP
        The RP component generates an Access Token in JWT format signed by the RP component and
        including the information of the Verifiable Credential needed to perform authorization.
    end note
   
    packetDeliverySIOP->customerSIOP : HTTP 200 with <access token>
    deactivate customerSIOP
    note right customerSIOP
        The wallet receives the response to the POST indicating the
        success or failure of the process.
        The web portal will refresh its content based on the information received
        by the Packet Delivery system.
    end note

    'Notify the portal so it refreshes the login page with services available to the customer
    packetDeliverySIOP-->packetDeliveryPortal --++: Notify with Verifiable Credential and\n<state>
    note over packetDeliverySIOP
        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:
        - 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.
        - The <Access Token> generated before

        The notification URL is configured in the RP component
    end note

end group

note over packetDeliverySIOP
   The authentication process has been finished and we still have to perform authorisation.
   At this point, Packet Delivery knows:
      1. That Happy Pets is a trusted participant entity
      2. That happy Pets says that the user is a customer
      3. The category of customer (Normal/Gold)
      4. Any user info encoded into the VC, like customer id

   However, Packet Delivery still does not know Happy Pets can issue credentials
   of type Gold (and also Normal). We will check this when the customer chooses a specific
   service, which could be avaliable to all customers (Normal) or only Gold customers

end note


group Authorisation

    packetDeliveryPortal-->customerBrowser --++: Refresh the screen with services available to customers\nand include <Access Token>

    'The customer selects to change the PTA
    customerBrowser->packetDeliveryPEP --++: Customer selects\n"Change PTA" on delivery order\nSend <Access Token>
    note over packetDeliveryPEP
        The Policy Enforcement Point (PEP) intercepts request and
        checks that the request includes an <Access Token> signed by Packet Delivery RP
    end note
    packetDeliveryPEP->packetDeliveryPEP: Validate\n<Access Token>
    note over packetDeliveryPEP
        The Policy Enforcement Point (PEP) asks the
        Policy Decision Point (PDP) to evaluate if the <Access Token>
        authorizes caller to access the target service ("Change PTA")
    end note

    packetDeliveryPEP->packetDeliveryPDP --++: Evaluate authorisation request for "Change PTA"\nwith <Access Token>

    note over packetDeliveryPDP
        Use information in <Access Token> to evaluate policies associated to
        customer roles in the token.
    end note
    'Check policies for this customer
    packetDeliveryPDP->packetDeliveryAR --++: Retrieve access policies\nfrom the PRP
    packetDeliveryAR->packetDeliveryPDP --++: Return policies
    packetDeliveryPDP->packetDeliveryPDP : Evaluate authorisation\nof user evaluating policies\nassociated to roles

    packetDeliveryPDP->packetDeliveryPEP --++:Authorisation granted
    packetDeliveryPEP->packetDeliveryPortal --++:Forward original request:\nChange PTA on delivery order\nwith <Access Token>

    packetDeliveryPortal->packetDeliveryPortal: Perform change\nRequest forwarded to\nContext Broker (not shown)
    packetDeliveryPortal->customerBrowser --:Change confirmed

end group

@enduml