# Resident Collects Permanent Resident Card

This use case concerns the resident receiving the mailer from USCIS, going to the digital PRC pickup website, and using their digital wallet to pick up the USCIS PRC.

## Prerequisites

1. Resident has received a Permanent Resident Card in the mail, with an associated Digital Permanent Resident Card insert with a custom AIID / QR code.
2. The Resident has setup up their qualified Digital Wallet.
1. This step can be explained on the insert, or once the user visits the USCIS website; but the assumption is the Resident can complete this step independently of this flow.

## Steps

1. (alt) The Resident downloads a suitable wallet application
2. The Resident scans the QR from the mailer
3. The Resident confirms they would like to obtain a digital PRC in the wallet app
4. The Resident is redirected to <code>[https://myaccount.uscis.gov](https://myaccount.uscis.gov) </code> and logs in (email, password, 2FA as required).
5. The Resident reviews the Terms and Conditions of the Digital PRC program.
6. (alt) The Resident is asked to enter their One Time Code (AIID) from the mailer
7. (alt) In case of failure to retrieve PRC Details with the given AIID, Resident is asked to retry with the correct AIID / Error Screen is displayed
8. Consent obtained from Resident to store the credential in the wallet
9. Resident is redirected back to the wallet
10. Credential shows in the wallet

## Results

1. The Resident can view their Digital PRC Verifiable Credential in their Wallet software.
2. A USCIS system (Issuer Service or PRC data service) records the successful delivery of the Digital PRC Verifiable Credential to the Resident;
1. Records the Verifiable Credential ID for the Resident’s account
1. Deactivates the One Time Code (?)
1. Follows any other required notification process, e.g. email to the Resident’s registered email address that the Credential has been issued, etc…

## Sequence Diagram - Phases

For clarity, the Digital PRC issuance process is split into 4 phases and documented as Sequence diagrams:
1. Phase 1 - Installation of Wallet App
2. Phase 2 - Metadata exchange between Wallet App and Credential Provider
3. Phase 3 - User Authentication and AIID Verification
4. Phase 4 - Credential Generation and PRC Issuance

## Sequence Diagram - Phase 1 - Installation of Wallet App

In this phase, we show the possible flows that a resident can use to install the Wallet application (App). Later, the Wallet App will be used to request a Digital PRC credential

sequenceDiagram
    participant H as Holder
    participant WA as Wallet APP
    participant MP as VC Market Place 
    participant CI as IDP (Issuer IDP)
    participant N  as Native Camera App
    autonumber
    alt  Resident requests Digital PRC outside the Wallet App
        H ->> N: Resident Scans the QR code from native camera app
        N ->> H: Redirects the user to the right app store
        H ->> WA: Installs the Wallet app and proceeds to the next step
    else Resident requests Digital PRC from the Wallet App
        alt Credential Issuer provides a list of credential via a Market place
            H ->> WA: Opens Wallet Application 
            WA ->> MP: Holder request a credential from a list of available credential
            MP ->> WA: Redirected to the next step
        else Credential Issuer displays a QR code for authenticated users
            H ->> WA: Opens the Wallet APP 
            WA ->> CI: Resident scans the QR code from the Wallet APP
            CI ->> WA: Redirected to the next step
        end
    end

## Sequence Diagram - Phase 2 - Metadata Exchange and Client Registration (OIDC4SSI)

In this phase, we show the steps involved in the metadata exchange process that happens between wallet and credential provider. This is a crucial phase for the wallet to understand the credential options and capabilities offered by the credential provider.

sequenceDiagram
    participant H as Holder
    participant WA as Wallet APP
    participant CP as Credential Provider (A part of the Issuer Web Service)
    autonumber
    WA ->> CP: Resolves the Credential Providers .well-known metadata endpoint
    note right of CP: This is a standard behaviour performing metadata discovery for OAuth2 / OIDC clients
    CP ->> WA: Returns the .well-known JSON document
    note right of WA: Process discovery document looking for "credential" related metadata elements, <br/> render credentials offered by the provider to the End-User
    WA ->> WA: 
    H ->> WA: End user selects that they would like to request for a PRC Credential
    alt Wallet not registered as a client for the Credential Provider (Performs Dynamic Client registration)
    note right of CP: This is a standard behaviour for OAuth2 / OIDC clients performing dynamic client registrations
    WA ->> CP: Dynamic Client Registration Request (request to /register endpoint)
    CP ->> WA: Dynamic Client Registration response including valid client_id (response from /register endpoint)
    end

## Sequence Diagram - Phase 3 - User Authentication and AIID verification (OIDC4SSI)

In this phase, we show the authentication steps required to obtain the access token to call the credential endpoint.

sequenceDiagram
    participant H as Holder
    participant WA as Wallet APP
    participant CP as Credential Provider (A part of the Issuer Web Service)
    participant CGS as Credential Generation service (A part of the Issuer Web Service)
    participant CI as myuscis.gov IDP
    participant PRC as PRC Data Interface 
    autonumber
    WA ->> CP: OAUTH2 / OIDC Authorization Request

    alt Standard OpenID Connect Flow 
    CP ->> CI: OIDC Authentication request to the USCIS IDP
    note right of CI: Only required if the user not already authenticated which is determined by the IDP
    CI ->> H: Authenticate user
    CI ->> H: Request Authorisation / consent for credential provisioning
    note right of CI: Whether or not the ID token returned in the redirect, is dependent on the configured behaviour of myuscis.gov IDP. <br/> If it is not, then the credential provider will exchange the obtained authorization code at the IDP's token endpoint to obtain ID_Token
    CI ->> CP: OIDC Authentication Response with ID_Token
    end

    note over WA,CP: The CP asks the Resident to enter their One Time Code (AIID - Application Invitation Identifier) <br/> from the mailer, if the AIID is not present in request 
    CP ->> H: Request AIID from the user
    H ->> CP: Submit AIID 
    CP ->> PRC: Query for a record matching sub and AIID combo
    note right of PRC:  If there is no match found, an error page informing the user of this would be returned.
    PRC ->> CP: Successful Query Response 
    CP ->> WA: OAUTH2 / OIDC Authorization Response with authorization code 

    

<details>
<summary> Phase 3 - User Authentication Request flow - Protocol Details</summary>

## Credential Request

- At Phase 2 - Step 1, the wallet prepares the following standard OAuth2 / OIDC authorization request to the credential provider

HTTP/1.1 302 Found
Location: https://prc-issuer.example.com/authorize?
response_type=code
&scope=prc
&client_id=s6BhdRkqt3
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Notes on this request
- Standard OAuth2 / OIDC Authorization request (As per RFC6749)
- Uses Authorization Code Flow (As per RFC6749)
- Uses PKCE with S256 Challenge method (As per RFC7646)
- Client ID used is obtained through registration (whether the registration process be dynamic or out-of-band)
- Other scopes are permitted to be present in the request (e.g. openid). However they are not required
- The value of the scope used in the request "prc" is free for us as a cohort to decide the final value of

As indicated above, it is a standard expected behaviour for the response to be a redirect. In this case, the configured credential provider further redirects the wallet to the underlying myuscis.gov idp to perform user authentication

- At Phase 3 - Step 2 - 5, are standard OpenID Connect flow. The flow can be [read about in detail on Okta's website](https://developer.okta.com/docs/concepts/oauth-openid/)

- At Phase 3 - Step 6 & 7, Accomplished using HTML & JS returned to the browser by the Credential Provider

- At Phase 3 - Step 10, Authorization code is sent back to the wallet after successful authentication.

    
HTTP/1.1 302 Found
Location: https://wallet.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA
    

</details>

## Sequence Diagram - Phase 4 - PRC Issuance (OIDC4SSI)

In this phase, PRC data retrieval, cryptogrpahic binding and credential genereration process is shown via sequence diagram.

sequenceDiagram
    participant H as Holder
    participant WA as Wallet APP
    participant CP as Credential Provider (A part of the Issuer Web Service)
    participant CGS as Credential Generation service (A part of the Issuer Web Service)
    participant CI as IDP
    participant AS as USCIS Authorization Server
    participant PRC as PRC Data Interface 
    autonumber
    WA ->> CP: Request access_token using obtained authorization code via Credential Provider's /token endpoint
    note right of CP: This is a Standard OAuth2 call to the token endpoint to exchange authorization code for an access_token (As per RFC6749)
    CP ->> WA: access_token granting access to credential endpoint for the authorized credential
 
    WA ->> WA: Generates a DID for cryptographic binding of the credential and prepares proof of possession <br/> of private key authorized via the public key listed in the DID document
    
    par Wallet requests copy of credential using the access token (This request can be repeated as long as the access token is valid)
        WA ->> CP: Request PRC Credential (using access_token to prove authorization)
        CP ->> CP: Validate Credential Request including the proof of possession against the supplied DID
        CP ->> AS: Request for client access_token to call PRC Data interface
        AS ->> CP: After success client authentication, returns client access_token
        CP ->> PRC: Query for a record matching sub and AIID combo from access_token (using client access_token)
        PRC ->> CP: Query Response (containing PRC user claims)
        CP -->> CGS: Generate PRC Credential request (using claims retreived from PRC database)
        CGS -->> CP: Generate PRC Credential
        CP ->> WA: "Issued Credential" 
    end

<details>
<summary> Phase 4 - PRC Credential Issuance via Credential Endpoint - Protocol Details</summary>

## Credential Request

- At Phase 4 - Step 1, Using the authorization code, the wallet requests for access_token via CP's Token Endpoint.

POST /token HTTP/1.1
Host: prc-issuer.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
grant_type=authorization_code
  &code=SplxlOBeZQQYbYS6WxSbIA
  &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
    

- At Phase 4 - Step 2, after successfull verification, CP's Token Endpoint responds with an access_token granting access to requested credential via Credential endpoint .

<TODO - Expand on C_nounce>

    
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ",
    "token_type": "bearer",
    "expires_in": 86400,
    "c_nonce": "tZignsnFbp",
    "c_nonce_expires_in": 86400
  }
    

- At Phase 4 - Step 3, Using the access_token obtained in the previous step, the wallet requests for a PRC credential via Credential Endpoint.

    
POST /credential HTTP/1.1
Host: prc-issuer.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW

type=prc
format=ldp%5Fvc
did=did%3Aexample%3Aebfeb1f712ebc6f1c276e12ec21
proof=%7B%22type%22:%22...-ace0-9c5210e16c32%22%7D
        

- At Phase 4 - Step 6, the client requests USCIS authorization server for client access_token to call PRC Data interface.

POST /token HTTP/1.1
Authorization: Basic YjY4Y2I2ZDctNGI5Yi00ODdkLThkZjktM2RkNzg4ZmYyZGEzOm5jalFDYjFJZkhTLW1UT nYuVDBycXVNdzBK
grant_type=client_credentials&scope=subject_data

- At Phase 4 - Step 7, After successfull authentication, the authorization servers responds with the access_token.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache 

{
    "access_token": "BH9OOtzzxsy8MPvqWlvbCV1GV4UfKrytlloW4YSOD..",
    "expires_in": 3599,
    "scope": "subject_data",
    "token_type": "bearer"
}

- At Phase 4 - Step 8, Query the PRC User data endpoint for the record matching the sub and AIID.

        
GET /1.0/subjects/data?aiid=FiIJethCqaTkWh70Gq8D&subjectReference=39874.K ENRBSUZ&holderDid=did:example:1234
Host: api.prc.example.com
Authorization: Bearer BH9OOtzzxsy8MPvqWlvbCV1GV4UfKrytlloW4YSODEU.
Content-Type: application/json
        

- At Phase 4 - Step 9, Query response is returned from the PRC User data endpoint.

        
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache       

{
    "subjectData": {
        "did":"did:example:1234"
        "image": "data:image/png;base64,iVBOR....=",
        "lprNumber": "1958-08-17",
        "gender": "Male",
        "residentSince": "2015-01-01",
        "givenName": "Louis",
        "familyName": "Pasteur",
        "birthCountry": "France",
        "commuterClassification": "C1",
        "birthDate": "1958-08-17",
        "lprCategory": "C09"
    }
}
        

- At Phase 4 - Step 12, The credential endpoint (after completing necessary background process) returns PRC credential in the requested format.

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

{
  "format": "ldp_vc"
  "credential" : "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L"
}
    

</details>