The globaliD Vault & PII Sharing

Verifications can contain personally identifiable information, or PII. The PII associated with a verification is always private. In some cases, partners may have a legal obligation to have access to some underlying PII data, or would request to share some way to connect with a user (ie email).

Note that verifications are public: when a user completes a set of required verifications, a partner application can view the list of verifications associated with an identity, along with additional details like the identity of the verifier, the type of verification, when it was verified, etc. For example:

       Date/Time              Verification                  Verifier    Public Data
       -------------------    --------------------------    --------    -----------
       2019-01-19 11:26:52    Has valid phone number        Twilio      USA
       2019-01-19 12_03:40    Has valid email address       Mandrill
       2019-01-19 12:08:28    Has valid Facebook account    Facebook

While the verification itself is public, the PII is not -- despite having the above set of public verifications associated with an identity, the email address, phone number and facebook account ID that was used to generate those verifications is not revealed.

globaliD is fervently dedicated to protecting user PII and further believes that in 90+% of cases, partner applications do not need the underlying PII information, just the verifications associated with a user.

At the moment, to setup the PII sharing feature, you must email verifications@global.id. In your email, please include the client_id of the application you wish to have PII access, legal requirements for accessing such information, and your corresponding application public key.



To view a sample node integration utilizing PII sharing and access to the globaliD vault, visit this globaliD open source project, which can be experienced here.

Prerequisites to accessing PII information

First, before interacting with PII information, developers and partner applications must complete the following:

  1. Setup a required verification and interact with the globaliD team to create an associated acrc_id.

  2. To be able to access PII data, make sure scope was set to openid during the user authorization process. In other words, when using globaliD connect or globaliD web client, make sure the following parameters were set:
    • scope = openid
    • grant_type or response_type ='code'
    • a randomly generated nonce

  3. Engage with the globaliD team to request PII sharing capabilities - email verifications@global.id or reach out on our Discord Server.

How it works


PII information currently resides in a multi-layered encrypted vault. For a partner to access a user's PII, they must:

  1. Exchanged an authorization_code retrieved during a signup flow for an access_token and an id_token; the id_token provides partners a list of values that a user has explicitly shared with them, which can be requested from the vault.

  2. Partners must request an access token for their application from the v1/auth/token endpoint.

  3. Call the vault API to access encrypted data associated with the list of values from a user's id_token from the first step

  4. Decrypt the payload using the corresponding private key registered to the encrypted client public key.

  5. To access files stored in the vault, namely photos, one must make a separate call to an /attachment endpoint.



Engaging with the Vault



Vault flow

1. Get an id_token for the user

When a user approves a login attempt on behalf of a partner, the tokens are encrypted with the partner's public key, along with generated passwords - partners will fetch these tokens and passwords to access underlying PII data. The PII data is then passed to the vault, where a record is created which partners can access with the above information and their public key.

The vault service requires that you use a user's access token and their id_token. This is returned with access token from the globaliD /auth/token endpoint. It is a JSON Web Token (JWT) which shares which claims a user has explicitly given consent for a partner application to view. These claims are the tokens mentioned above. The JWT payload of the id_toke looks like so:

// JWT payload part of the id_token

{
    "iss":"http://server.example.com",
    "sub":"248289761001",
    "aud":"s6BhdRkqt3",
    "nonce":"n-0S6_WzA2Mj",
    "exp": 1311281970,
    "iat": 1311280970,
    "https://claims.idp.globalid.net/claims/${acrc_id}":
        {"${consent_id}": ["encrypted_data_tokens_with_partners_public_key"]}
}



2. Get an application access_token

Next, partner applications must make sure they have an access_token for their application using the /auth/token endpoint. Make sure the grant_type is set to client_credentials and use the associated client_id and client_secret keys. This access token should be cached to minimize the amount of times it is called.

return await axios.request({
    method: 'post',
    url: '/auth/token',
    baseURL: process.env.GID_API_BASE_URL,
    headers: {'Content-Type': 'application/json'},
    data: {
        client_id: process.env.CLIENT_ID,
        client_secret: process.env.CLIENT_SECRET,
        grant_type: 'client_credentials',
    }
});



3 Retrieve encrypted PII data

After fetching an access token for the application, call the Vault API to get the associated PII data. Use the GET /v1/vault/get-encrypted-data endpoint using the claims_ids from the _id_token_ from the user as well as the application's access_token.

return axios.request(`${process.env.GID_API_BASE_URL}/vault/get-encrypted-data`, {
    method: 'post',
    data: {
        private_data_tokens: claims_tokens, // array of tokens from the user id_token
    },
    headers: {
        'Authorization': `Bearer ${access_token}`,
    },
    json: true,
})



The response from the /v1/vault/get-encrypted-data will look like this:

[
  {
    encrypted_data_password: "encrypted password to decrypt encrypted_data", 
    encrypted_data: "encrypted PII, should be decrypted with password from encrypted_data_password",
    encrypted_root_password: "encrypted password", 
  },
...]



4. Decrypt the Vault response

Partners must decrypt the data payload by first decrypting the associated password using the associated private key for their application, and using that decrypted value to decrypt the PII data.

// decrypt passwrod from /get-encrypted-data 
const pass = RSADecrypt(data[0].encrypted_data_password, privateKey); 
const root_password = RSADecrypt(data[0].encrypted_root_password, privateKey);

// decrypt data using decrypted password 
const tokenData = AESDecrypt(data[0].encrypted_data, pass); 

// output tokenData 
console.log(JSON.parse(tokenData)) 

""" 
{ 
  value: "John", 
  type: "legal_first_name", 
  gid_uuid:"6c42df5b-8081-4912-8f1a-61d990e3f3ad", 
  attestation_request_uuid:` `"f034a1d9-6fb0-4bcb-8ba7-7cbbc91989 
  has_attachment: true 
} 
"""



Upon completing this flow, partners will have access to the PII data users have consented to share with them.

Accessing Files from the Vault

To access the files store, partner applications must make a call to a different endpoint to access this.

For every value returned from the /vault/get-encrypted-data endpoint, the unencrypted data value has a key private_file_token. If this value is set, grab this underlying "attachment" by calling the /vault/attachment/${private_file_token}/client endpoint. Upon receiving the response, partners should decrypt this value using the password returned from the vault/get-encrypted-data endpoint.

axios.request(devurl, {
    method: 'get',
    headers: {
        Authorization: `Bearer ${access_token}`,
    },
}).pipe(crypto.default.aes.decryptStream(attachment.password))
    .on('data', (chunk) => {
        chunks.push(chunk)
    })
    .on('error', reject)
    .on('finish', () => {
        resolve(`data:${piiValue.mime_type};base64,${Buffer.concat(chunks).toString('base64')}`)
    })
})



A Note on Security

globaliD's vault has been built using the latest cryptographic techniques and with the user at the center of the experience. A user's PII data is encrypted using: - A generated password only they have access to and - The partner's public key.
These multiple layers of encryption not only make certain that hackers cannot access the undelrying PII data while it is in the vault, but also ways of protecting user data upon a breach of a partner's private key or a breach of a user's device or password. globaliD simply re-encrypts the associated data with this breach with a new set of values and minimizes exposure to underlying PII data.



For more information or questions on the Vault and accessing PII data, please reach out to us in our discord channel or email devSupport@global.id.