2nd Factor Authentication Events

auth-events.yaml

swagger: '2.0'
info:
  version: v1
  title: SxS Events
  description: 'Events described here tell you what happens during the use of **tokens** to authenticate users and confirm transactions.'
  contact:
    name: Igor Vlahek
    email: igor.vlahek@asseco-see.hr


produces:
  - application/json
paths:
  /events:
    get:
      responses:
        default:
          description: OK

definitions:
  event:
    description: Base model of 2nd factor authentication events
    discriminator: kind
    required:
      - kind
    properties:
      event-id:
        type: string
        format: uuid
        description: Unique identifier of event instance in UUID format    
      occurred-on:
        type: string
        format: date-time
        description: Time when an event occurred
      serial-number:
        description: Serial number of a token. Unique for each key material.
        type: string
      primary-user-id:
        description: Primary identifier of user used by application that uses 2nd factor authentication services
        type: string    
      secondary-user-id:
        description: Alternative identifier of user used by application that uses 2nd factor authentication services      
        type: string
      kind:
        type: string
        description: Unique kind of event published by SxS
        enum:
          - token-assigned # serial-number, token-id, primary-user-id, secondary-user-id
          - token-activated # covers also tokens activated on another device
          - token-migrated
          - token-blocked-permanently
          - token-blocked-temporarely
          - token-pin-changed
          - token-pin-change-failed
          - transaction-confirmed # transaction-id, map of fields used for confirmation (account, amount)
          - transaction-confirmation-failed
          - transaction-declined
          - authentication-failed # authentication-function (otp, mac...), failure-reason
          - authentication-suceeded
          - token-compromise-suspected # what signs fo compromise are present (jailbreak, rooting etc)          
  token-assigned:
    description: Token is assigned to user
    allOf:
      - $ref: '#/definitions/event'
      - type: object
        properties:
          file-name:
            type: string
    example:
      kind: 'token-assigned'
      occurred-on: '2015-11-19T13:21:01.000Z'
      id: '736a07bd-809e-43bd-9ac1-20991a78f390'
      serial-number: 788817721
      primary-user-id: 'john.doe'
      secondary-user-id: 'A78F39020991'
  
  
  authentication-failed:
    description: 2nd factor authentication failed
    allOf:
      - $ref: '#/definitions/event'
      - type: object
        properties:
          device-id:
            description: Unique identifier of a device used for soft token
            type: string
          device-ip-address:
            description: IP address of a device used for soft token    
            type: string
            format: ipv4
          failure-reason:
            type: string
            enum: [token-blocked, invalid-otp]
          auth-function:
            type: string
            enum:
            - otp 
            - mac
    example:
      kind: 'authentication-failed'
      occurred-on: '2015-11-19T13:21:01.000Z'
      id: '736a07bd-809e-43bd-9ac1-20991a78f390'
      serial-number: 788817721
      primary-user-id: 'john.doe'
      secondary-user-id: 'A78F39020991'
      device-id: 'A78F39020991-9ac120991a78f390'
      device-ip-address: '78.12.89.1'
      failure-reason: 'invalid-otp'
      auth-function: 'otp'
      
      
  transaction-confirmed:
    description: Token is assigned to user
    allOf:
      - $ref: '#/definitions/event'
      - type: object
        properties:
          device-id:
            description: Unique identifier of a device used for soft token
            type: string
          device-ip-address:
            description: IP address of a device used for soft token    
            type: string
            format: ipv4        
          transaction-id:
            description: 'Identiier of transaction (payment, consent, etc) that was confirmed'
            type: string
          transaction-fields:
            $ref: '#/definitions/string-map'
    example:
      kind: 'transaction-confirmed'
      occurred-on: '2015-11-19T13:21:01.000Z'
      id: '736a07bd-809e-43bd-9ac1-20991a78f390'
      serial-number: 788817721
      primary-user-id: 'john.doe'
      secondary-user-id: 'A78F39020991'
      device-id: 'A78F39020991-9ac120991a78f390'
      device-ip-address: '78.12.89.1'
      transaction-id: '9ac120991a78f390'
      transaction-fields:
        account: 'AT180000289188998129'
        amount: '110.54 EUR'
        creditor: 'Amazon llc.'
        payment-provider: 'iPay'
        payment-id: '9ac120991a78f390'        
  
  # String map in swagger means that map key will be represented as JSON keys and map values will be represented as JSON string values
  string-map:
    additionalProperties:
      type: string
    example:
      account: 'AT180000289188998129'
      amount: '110.54 EUR'
      creditor: 'Amazon llc.'
      payment-provider: 'iPay'
      payment-id: '9ac120991a78f390'