security-proxy-auth.yaml

openapi: 3.1.0
info:
  title: Edge Foundry - Proxy Authentication API
  description: This is the definition of the API for the Security Proxy Auth service in the EdgeX Foundry IOT microservice platform.
  version: 4.0.0

servers:
  - url: http://localhost:59842/api/v3
    description: URL for local development and testing

components:
  schemas:
    BaseResponse:
      description: "Defines basic properties which all use-case specific response DTO instances should support"
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
          example: v3
        requestId:
          description: "Uniquely identifies the request that resulted in this response."
          type: string
          format: uuid
          example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
        message:
          description: "A field that can contain a free-form message, such as an error message."
          type: string
        statusCode:
          description: "A numeric code signifying the operational status of the response."
          type: integer
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
      description: "A response type for returning a generic error to the caller."
      type: object
    PingResponse:
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        timestamp:
          description: "Outputs the current server timestamp in RFC1123 format"
          example: "Mon, 02 Jan 2006 15:04:05 MST"
          type: string
        serviceName:
          description: "Outputs the name of the service the response is from"
          type: string
    VersionResponse:
      description: "A response returned from the /version endpoint whose purpose is to report out the latest version supported by the service."
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        version:
          description: "The latest version supported by the service."
          type: string
        serviceName:
          description: "Outputs the name of the service the response is from"
          type: string
    ConfigResponse:
      description: "Provides a response containing the configuration for the targeted service."
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        serviceName:
          description: "Outputs the name of the service the response is from"
          type: string
        config:
          description: "An object containing the service's configuration. Please refer the configuration documentation of each service for more details at [EdgeX Foundry Documentation](https://docs.edgexfoundry.org)."
          type: object
    BaseRequest:
      description: "Defines basic properties which all use-case specific request DTO instances should support."
      type: object
      properties:
        requestId:
          description: "Uniquely identifies this request. For implementation, recommend this value be generated by the type's constructor."
          type: string
          format: uuid
          example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
          example: "v3"
    SecretRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
      description: Defines the secret data to be stored
      type: object
      properties:
        secretName:
          description: Specifies the location within the secret to store
          type: string
          example: "credentials"
        secretData:
          description: A list of the key/value pairs of secret data to store
          type: array
          items:
            $ref: '#/components/schemas/SecretDataKeyValue'
    SecretDataKeyValue:
      description: Defines a key/value pair of the secret data
      type: object
      properties:
        key:
          description: The key to identify the secret
          type: string
          example: "username"
        value:
          description: The value of the secret
          type: string
          example: "mqtt-user"
      required:
        - key
        - value
    AddKeyDataRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
      description: "A request for ingesting a new key"
      type: object
      properties:
        keyData:
          $ref: '#/components/schemas/KeyData'
      required:
        - keyData
    KeyData:
      description: "Indicates the information of a key."
      properties:
        issuer:
          description: "The issuer of the key"
          type: string
        type:
          description: "The type of the key.  Default value verification if it is empty."
          enum:
            - verification
            - signing
        key:
          description: "The key content"
          type: string
      required:
        - issuer
        - password
        - role
    GetKeyDataResponse:
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        keyData:
          $ref: '#/components/schemas/KeyDataResponse'
    KeyDataResponse:
      type: object
      properties:
        issuer:
          description: "The issuer of the key"
          type: string
        type:
          description: "The type of the key"
          type: string
        key:
          description: "The key content"
          type: string

  parameters:
    correlatedRequestHeader:
      in: header
      name: X-Correlation-ID
      description: "A unique identifier correlating a request to its associated response, facilitating tracing through being included on requests originating from the initiating request."
      schema:
        type: string
        format: uuid
      required: true
      example: "14a42ea6-c394-41c3-8bcd-a29b9f5e6835"
    OriginalRequestUriHeader:
      in: header
      name: X-Forwarded-Uri
      required: false
      description: original request URI
      schema:
        type: string
    OriginalRequestMethodHeader:
      in: header
      name: X-Forwarded-Method
      required: false
      description: original request method
      schema:
        type: string
    BearerTokenHeader:
      in: header
      name: Authorization
      required: true
      description: Bearer token authentication
      schema:
        type: string
      example: "Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJiOWQ0ZDhhYi0wMzk5LTQ0ZmYtYWQ5Ni1hNGUyMTE3MmM1YzIiLCJleHAiOjE2NTcwODQ5OTksIm5iZiI6MTY1NzA4MTM5OSwiaWF0IjoxNjU3MDgxMzk5fQ.WvuSULWKfROzygV-V1LobsjlK5aU88CRNnOgabfzdB6bD5IK2HXw8tD3XLL3xOfTBNnyQkRnqFVbZJ9zkyW_Ng"
    offsetParam:
      in: query
      name: offset
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: "The number of items to skip before starting to collect the result set."
    limitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: -1
        default: 20
      description: "The numbers of items to return.  Specify -1 will return all remaining items after offset.  The maximum will be the MaxResultCount as defined in the configuration of service."

  headers:
    correlatedResponseHeader:
      description: "A response header that returns the unique correlation ID used to initiate the request."
      schema:
        type: string
        format: uuid
      example: "14a42ea6-c394-41c3-8bcd-a29b9f5e6835"
  examples:
    RolePolicyExample:
      value:
        apiVersion: v3
        rolePolicy:
          role: device-cmd-dev
          description: The device command developer role which can execute all the device commands
          accessPolicies:
            - path: /core-command/*
              httpMethods:
                - GET
                - PUT
              effect: allow
            - path: /core-metadata/api/v3/device/*
              httpMethods:
                - GET
                - PUT
                - POST
              effect: deny
    GetRolePolicyExample:
      value:
        apiVersion: v3
        statusCode: 200
        rolePolicy:
          id: 2faeb932-fc82-4c3c-8de5-4f5a191240ec
          role: device-cmd-dev
          description: The device command developer role which can execute all the device commands
          created: 1600927134931
          modified: 1600927134931
          accessPolicies:
            - path: /core-command/*
              httpMethods:
                - GET
                - PUT
              effect: allow
            - path: /core-metadata/api/v3/device/*
              httpMethods:
                - GET
                - PUT
                - POST
              effect: deny
    MultiRolePolicyExample:
      value:
          apiVersion: v3
          statusCode: 200
          totalCount: 1
          rolePolicies:
            - id: 2faeb932-fc82-4c3c-8de5-4f5a191240ec
              role: device-cmd-dev
              created: 1600927134931
              modified: 1600927134931
              accessPolicies:
                - path: /core-command/*
                  httpMethods:
                    - GET
                    - PUT
                - path: /core-metadata/api/v3/device/*
                  httpMethods:
                    - GET
                    - PUT
                    - POST
              effect: allow
    400Example:
      value:
        apiVersion: "v3"
        requestId: "73f0932c-0148-11eb-adc1-0242ac120002"
        statusCode: 400
        message: "Bad Request"
    401Example:
      value:
        apiVersion: "v3"
        requestId: "73f0932c-0148-11eb-adc1-0242ac120002"
        statusCode: 401
        message: "Unauthorized"
    403Example:
      value:
        apiVersion: "v3"
        requestId: "73f0932c-0148-11eb-adc1-0242ac120002"
        statusCode: 403
        message: "Forbidden"
    404Example:
      value:
        apiVersion: "v3"
        requestId: "84c9489c-0148-11eb-adc1-0242ac120002"
        statusCode: 404
        message: "Not Found"
    409Example:
      value:
        apiVersion: "v3"
        statusCode: 409
        message: "Data Duplicate"
    416Example:
      value:
        apiVersion: "v3"
        statusCode: 416
        message: "Range Not Satisfiable"
    500Example:
      value:
        apiVersion: "v3"
        statusCode: 500
        message: "Interval Server Error"
    AddUserExample:
      value:
        - apiVersion: v3
          user:
            name: bob
            displayName: Bob Myers
            description: A device user
            password: password
            roles:
              - device-admin
    LoginRequestExample:
      value:
        username: "alice"
        password: "***************"
    LoginRespExample:
      value:
        apiVersion: v3
        statusCode: 200
        jwt: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzA4ODIxNjIsImlzcyI6IklPVGVjaCIsInRva2VuX2lkIjoiZTcxMDMwYzQtZDgxMS00Y2Y1LThmMjktYTg3YWE2ZDY0NTRkIn0.TPlUmcwAkWUC3_WRFC1Pp3sjbG4EmXLXrqow387et0N3z9tNZ-zqH6jfNzOATcj5I7-Wrkp-T0fFfbhGidPYBg
    RefreshTokenRespExample:
      value:
        apiVersion: v3
        statusCode: 200
        jwt: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzA4ODIxNjIsImlzcyI6IklPVGVjaCIsInRva2VuX2lkIjoiZTcxMDMwYzQtZDgxMS00Y2Y1LThmMjktYTg3YWE2ZDY0NTRkIn0.TPlUmcwAkWUC3_WRFC1Pp3sjbG4EmXLXrqow387et0N3z9tNZ-zqH6jfNzOATcj5I7-Wrkp-T0fFfbhGidPYBg
    GetUserExample:
      value:
        apiVersion: v3
        statusCode: 200
        user:
          name: bob
          displayName: Bob Myers
          description: A device user
          roles:
            - device-admin
    MultiAddUserExample:
      value:
        - apiVersion: "v3"
          requestId: "592b98aa-1e4e-46f2-992a-9e6ef844270f"
          statusCode: 201
        - apiVersion: "v3"
          requestId: "8e025b94-1512-4ec4-a9bd-3111cb278379"
          statusCode: 400
          message: "role policy 'not-exists-role' not exists"
        - apiVersion: "v3"
          requestId: "8e025b94-1512-4ec4-a9bd-3111cb278379"
          statusCode: 409
          message: "user name 'user' already exists"
    MultiUpdateUserExample:
      value:
        - apiVersion: "v3"
          requestId: "592b98aa-1e4e-46f2-992a-9e6ef844270f"
          statusCode: 200
        - apiVersion: "v3"
          requestId: "8e025b94-1512-4ec4-a9bd-3111cb278379"
          statusCode: 400
          message: "role policy 'not-exists-role' not exists"
        - apiVersion: "v3"
          requestId: "8e025b94-1512-4ec4-a9bd-3111cb278379"
          statusCode: 404
          message: "user 'user' does not exist"
    MultiUserExample:
      value:
        apiVersion: v3
        statusCode: 200
        totalCount: 2
        users:
          - name: bob
            displayName: Bob Myers
            description: A device user
            roles:
              - device-admin
          - name: alice
            displayName: Alice Masur
            description: A device profile user
            roles:
              - device-profile-admin
    MultiAuthRouteRequestExample:
      value:
        - apiVersion: v3
          authRoute:
            path: /core-metadata/api/v3/device/*
            httpMethod: GET
        - apiVersion: v3
          authRoute:
            path: /core-data/api/v3/event
            httpMethod: POST
    MultiAuthRouteResponseExample:
      value:
        apiVersion: v3
        statusCode: 200
        authResponses:
          - path: /core-metadata/api/v3/device/*
            httpMethod: GET
            authResult: true
          - path: /core-data/api/v3/event
            httpMethod: POST
            authResult: false
    AddKeyDataExample:
      value:
        apiVersion: v3
        keyData:
          issuer: bob
          type: verification
          key: g2ymJgt6hlYk92My89wpeYL3yH0WoiM9
    GetKeyDataExample:
      value:
        apiVersion: v3
        statusCode: 200
        keyData:
          issuer: bob
          type: verification
          key: g2ymJgt6hlYk92My89wpeYL3yH0WoiM9

paths:
  /auth:
    parameters:
      - $ref: '#/components/parameters/BearerTokenHeader'
      - $ref: '#/components/parameters/OriginalRequestUriHeader'
      - $ref: '#/components/parameters/OriginalRequestMethodHeader'
    get:
      summary: Authenticate the user
      description: |
        Authenticate the user based on the JWT provided in the headers.
      responses:
        '204':
          description: "The user is authorized with the requested URI and the operation."
        '401':
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                401Example:
                  $ref: '#/components/examples/401Example'
        '403':
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                403Example:
                  $ref: '#/components/examples/403Example'
  /key:
    post:
      summary: Add a new key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddKeyDataRequest'
            examples:
              addKeyDataExample:
                $ref: '#/components/examples/AddKeyDataExample'
      responses:
        '201':
          description: "Created"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                statusCode: 201
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400Example:
                  $ref: '#/components/examples/400Example'
        '409':
          description: "Conflicted"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                409Example:
                  $ref: '#/components/examples/409Example'
        '500':
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
  /key/verification/issuer/{issuer}:
    parameters:
      - name: issuer
        in: path
        required: true
        schema:
          type: string
        description: "Specifies the issuer of the key"
    get:
      summary: Get a key information by the specified issuer
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKeyDataResponse'
              examples:
                LoginRespExample:
                  $ref: '#/components/examples/GetKeyDataExample'
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400Example:
                  $ref: '#/components/examples/400Example'
        '404':
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                404Example:
                  $ref: '#/components/examples/404Example'
        '500':
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
  /secret:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: Stores a secret to the secure Secret Store
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SecretRequest'
        required: true
      responses:
        '201':
          description: "Created"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: "Invalid request."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400Example:
                  $ref: '#/components/examples/400Example'
        '500':
          description: "An unexpected error happened on the server."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
  /config:
    get:
      summary: "Returns the current configuration of the service."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
              example:
                apiVersion: "v3"
                config:
                  Writeable:
                    LogLevel: "INFO"
                  Databases:
                    Primary:
                      Type: "redisdb"
                      Timeout: 5000
                      Host: "edgex-redis"
                      Port: 6379
                      Name: "proxy-auth"
                  Registry:
                    Host: "localhost"
                    Port: 8500
                    Type: "consul"
                  Service:
                    HealthCheckInterval: "10s"
                    Host: "proxy-auth"
                    Port: 59842
                    SeverBindAddr: ""
                    StartupMsg: "This is the Core Data Microservice"
                    MaxResultCount: 50000
                    MaxRequestSize: 0
                    RequestTimeout: "5s"
                  SecretStore:
                    Type: "vault"
                    Host: "edgex-vault"
                    Port: 8200
                    Path: "security-proxy-auth"
                    Protocol: "http"
                    Namespace: ""
                    RootCaCertPath: ""
                    ServerName: ""
                    Authentication:
                      AuthType: "X-Vault-Token"
                      AuthToken: ""
                    TokenFile: "/tmp/edgex/secrets/security-proxy-auth/secrets-token.json"
                  serviceName: "proxy-auth"
        '500':
          description: "Interval Server Error"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
  /ping:
    get:
      summary: "A simple 'ping' endpoint that can be used as a service healthcheck"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
              example:
                apiVersion: "v3"
                timestamp: "Mon, 02 Jan 2006 15:04:05 MST"
                serviceName: "proxy-auth"
        '500':
          description: "Interval Server Error"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
  /version:
    get:
      summary: "A simple 'version' endpoint that will return the current version of the service"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
              example:
                apiVersion: "v3"
                version: "master"
                serviceName: "proxy-auth"
        '500':
          description: "Interval Server Error"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'