uport-project / specs

uPort Protocol Specs
Apache License 2.0
86 stars 24 forks source link

Add support for OpenID like `claims` specs in request #52

Closed pelle closed 5 years ago

pelle commented 5 years ago

A Claims Spec allows you to request claims with very specific properties. This is based on the claims spec in OpenID-Connect but adapted to support Verifiable Claims.

This replaces the requested and verified parameters of this request. You may still include requested and verified to provide support for older clients. But they will be ignored if by newer clients if the claims field is present.

{
  iss: 'did:web:somesite.com',
  type: 'shareReq',
  claims: {
    verifiable: {
      email: {
        iss: [
          {
            did: 'did:web:uport.claims',
            url: 'https://uport.claims/email'
          },
          {
            did: 'did:web:sobol.io',
            url: 'https://sobol.io/verify'
          }
        ],
        reason: 'Whe need to be able to email you'
      },
      nationalIdentity: {
        essential: true,
        iss: [
          {
            did: 'did:web:idverifier.claims',
            url: 'https://idverifier.example'
          }
        ],
        reason: 'To legally be able to open your account'
      }
    },
    user_info: {
      name: { essential: true, reason: "Show your name to other users"},
      country: null
    }
  }
}

Verifiable Claims Spec

This is an json object that lives at the verifiable key within the claims object. It is not required, but provides you flexibility in clearly specifying the kind of claims you need.

Name Description Required
type The key in the verifiable object is the claims type requested yes
essential This claim is essential. A response should not be returned if user does not have this claim no
iss Array of {did, url} objects where did is DID of allowed issuer of claims and url is URL for obtaining claim, did is required but url is not no
reason Short string explaining why you need this no

Examples:

{
  email: {
    essential: true,
    iss: [
      {
        did: 'did:web:uport.claims',
        url: 'https://uport.claims/email'
      },
      {
        did: 'did:web:sobol.io',
        url: 'https://sobol.io/verify'
      }
    ],
    reason: 'Whe need to be able to email you' 
  }
}

User Info Spec

This is an json object that lives at the user_info key within the claims object. It is not required, but provides you flexibility in clearly specifying the kind of self presented user claims you need.

NOTE: These are claims specifically made by the user themselves and are not verifiable by an external party.

Name Description Required
type The key in the verifiable object is the claims type requested yes
essential This claim is essential. A response should not be returned if user does not have this claim no
reason Short string explaining why you need this no

Per the OpenId spec if the value of the claim type in the object is null then it is a non essential value.

Examples:

{
  email: {
    essential: true,
    reason: 'Whe need to be able to email you' 
  },
  name: null,
  phone: {
    reason: 'So we can notify you by text'
  }
}