peacekeeper commented 4 years ago

New Work Item Proposal

This Work Item is being proposed by several companies who have received a Silicon Valley Innovation Program (SVIP) award on "Preventing Forgery & Counterfeiting of Certificates and Licenses", by the U.S. Department of Homeland Security's (DHS) Science and Technology Directorate (S&T).

The scope of this Work Item is to define common APIs for Issuers and Verifiers of digital credentials based on standards such as the Verifiable Credentials Data Model (https://www.w3.org/TR/vc-data-model/), JWT (https://tools.ietf.org/html/rfc7519), Open Badges (https://openbadges.org/), and potentially others.

This is NOT about communication between Issuers, Holders, and Verifiers, i.e. this is NOT an alternative or competing proposal to CHAPI, OIDC, WebAuthn, DIDComm, etc. These are only INTERNAL APIs that e.g. an Issuer or a Verifier would use to interface with their own internal backend systems. Authentication and authorization are out-of-scope.

Include Link to Abstract or Draft

List Owners

Co-Editors:

Markus Sabadello (@peacekeeper)
Manu Sporny (@msporny)
Mike Varley (@mavarley)
Carl DiClementi (@cahl-dee)

jandrieu commented 4 years ago

This looks like a strong work item. Markus has also sent the proposal to the community email list.

Let's give this the holidays to percolate. I'd like to take it up in our first meeting in 2020.

David-Chadwick commented 4 years ago

We have developed our own internal APIs which are somewhat different to the above.

The issuer API interfaces to the organisations LDAP or other directory service, retrieves the user's attributes, and creates VCs based on these.
The verifier API accepts a VP and returns the verified subject's attributes from the embedded VCs. Both the VP and VCs are verified.

peacekeeper commented 4 years ago

@David-Chadwick sounds great, can you share this? Perhaps we can re-use some of your work or learn from it?

David-Chadwick commented 4 years ago

Yes, we have defined it internally using Swagger and YAML. Let me talk to my developers about releasing this to the list

David-Chadwick commented 4 years ago

Here is the YAML for the VC issuer service interacting with an identity provider/attribute authority that is assumed to have a backend LDAP or AD or equivalent database. You should copy the YAML into https://editor.swagger.io/ in order to see it. There are two services:

one to authenticate the subject/holder to the IdP
one to obtain the list of attributes that the IdP is willing to publish as VCs for the subject, returned formatted as JSON objects. The VC Issuer service interacts with the subject/holder (protocol out of scope) and issues VCs to the subject when requested, based on the attributes held by the IdP/AA.
```
openapi: 3.0.0
info:
title: IdP/AA
description: RPC API for Identity Provider/Attribute Authority
version: '1.0'
contact:
name: University of Kent
url: 'https://www.kent.ac.uk'
email: ioram7@gmail.com
```

tags:

name: Attribute Authority description: Attribute Authority

servers:

url: https://idp:1880/v1

paths: /authenticate: post: tags:

Attribute Authority summary: Authenticates the user description: Authenticates the user to the IdP/AA by passing authnCreds via the body of the request. operationId: Authenticate requestBody: content: application/json: schema: $ref: '#/components/schemas/idpAuthnCredsObject' responses: '200': description: "OK - The returned userHandle is a string" content: application/json: schema: $ref: '#/components/schemas/idpAuthenticateResponse' '401': description: "Authentication Failure" content: text/plain: schema: type: string example: "Authentication Failure"

/getAllAttrs/{userHandle}: get: tags:
Attribute Authority summary: "Returns all the users attributes" description: "Returns all the users attributes except the authnCreds" operationId: GetAllAttrs parameters:
name: userHandle in: path description: "The users handle" required: true schema: type: string responses: '200': description: "OK" content: application/json: schema: $ref: '#/components/schemas/idpAttrSet'

components: schemas: idpAuthnCredsObject: type: object properties: authnCreds: type: object example: username: "dc1" otp: "abcdef"

idpAuthenticateResponse:
  type: object
  properties:
    userHandle:
      type: string
      example: "dc1UserHandle"
    username:
      type: string
      example: "dc1"
  required:
    - username
    - userHandle

idpAttrSet:
  type: array
  items:
    $ref: '#/components/schemas/idpAttrSetItem'

idpAttrSetItem:
  type: object
  properties:
    "@context":
      type: array
      items:
        type: string
    type:
      type: array
      items:
        type: string
  required:
    - "@context"
    - type
  additionalProperties: true

David-Chadwick commented 4 years ago

Here is the Verifier API YAML. This verification service is offered to relying parties to tell it if the holder has provided sufficient VCs to meet the RP's policy. The input parameters are:

a VP (we are using JWT signed VPs) with encapsulated VCs
a policyMatch object that indicates the RP's policy that the VP must match
a boolean saying whether the subject's attributes should be returned or not The response comprises: a boolean (granted or denied) an optional authentication token that identifies the subject to the RP the list of subject attributes (only if requested)

openapi: 3.0.0
info:
  title: VC Verifier
  description: RPC API For VC Verifier
  version: '1.0'
  contact:
    name: University of Kent
    url: 'https://www.kent.ac.uk'
    email: ioram7@gmail.com

tags:
  - name: VC Verifier
    description: VC Verifier

servers:
  - url: "https://vcverifier:8443/v1"

paths:
  /RequestAccessDecision:
    post:
      tags:
        - VC Verifier
      summary: Request Access Decision
      description: Request access decision
      operationId: requestAccessDecision
      requestBody:
        description: Policy Match, Verifiable Presentation, and Authentication Credentials
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VP"
      responses:
        '200':
          description: Access Granted
          content:
            application/json:
              schema:
                type: object
                properties:
                  granted: 
                    type: boolean
                    example: true
                  authnCreds:
                    type: object
                    example:
                      username: "dc1"
                      otp: "abcdef"
                  atts:
                    type: object
                    example: 
                      "@context": ["https://www.w3.org/2018/credentials/v1","https://www.kent.ac.uk/VCcontext/v1"]
                      type: ["VerifiableCredential", "DrivingLicenseCredential"]
                      name: "dainis"
                      surname: "grinbergs"
                      driving:
                        name: "dainis grinbergs"
                        DOB: "01/01/2000"
                        vechicle: "car, moped, bike"
        '400':
          description: Badly Formed Request or VP Verification failure or VP directed to URL of different SP or Badly formed policy tree.
        '404':
          description: No Matching Policy
        '401':
          description: VC not issued to VC Holder or VC not issued by a trusted issuer or User Registration Required at VC Issuer
        '500':
          description: Internal Server Error

components:
  schemas:
    VP:
      type: object
      properties:
        atts:
          type: boolean
          example: true
        policyMatch:
          type: object
          example:
            type: "Over 18"
        vpjwt:
          type: string
          example: "eyJ1c2VybmFtZSI6ImRnMSIsImF0dHNldCI6W3siQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy5kdmxhLmdvdi51ay9WQ2NvbnRleHQvdjEiXSwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIkRyaXZpbmdMaWNlbnNlQ3JlZGVudGlhbCJdLCJuYW1lIjoiZGFpbmlzIiwic3VybmFtZSI6ImdyaW5iZXJncyIsImRyaXZpbmdMaWNlbnNlIjp7Im5hbWUiOiJkYWluaXMgZ3JpbmJlcmdzIiwiRE9CIjoiMDEvMDEvMjAwMCIsInZlaGljbGVzIjoiY2FyLCBtb3BlZCwgYmlrZSJ9fSx7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly93d3cua2VudC5hYy51ay9WQ2NvbnRleHQvdjEiXSwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIkRlZ3JlZUNyZWRlbnRpYWwiXSwicHJvcDEiOiJ2YWwxIiwicHJvcDIiOiJ2YWwyIiwiZGVncmVlIjp7InR5cGUiOiJCYWNoZWxvckRlZ3JlZSIsIm5hbWUiOiJCYWNoZWxvciBvZiBTY2llbmNlIGFuZCBBcnRzIn19XSwiYXV0aG5DcmVkcyI6eyJ1c2VybmFtZSI6ImRnMSIsIm90cCI6ImFiY2RlZiJ9fQ=="

peacekeeper commented 4 years ago

@David-Chadwick thanks for sharing, this is great input!

w3c-ccg / community

[PROPOSED WORK ITEM] Credential Issuer and Verifier APIs #102

New Work Item Proposal

Include Link to Abstract or Draft

List Owners