openapi: 3.0.0
info:
  title: IED Auth APIs
  version: '1.0'
  description: IED Auth API documentation.
  contact:
    name: Team ADI
  license:
    name: Industrial Edge © 2022, Siemens AG. All rights reserved.
servers:
  - url: https://localhost/device/edge/a.service/beta/api/v1
tags:
  - name: SystemRoles
    description: Edge auth service system roles
paths:
  /system/roles:
    get:
      tags:
        - SystemRoles
      summary: List all roles of an system.
      responses:
        '200':
          $ref: '#/components/responses/SystemRoles'
        '401':
          $ref: '#/components/responses/errorUnauthenticated'
        "403":
          $ref: "#/components/responses/errorForbidden"
        '500':
          $ref: '#/components/responses/genericError'
      operationId: get-system-roles
      description: |-
        - Get System Role is a function used to retrieve the current roles.
      parameters:
        - $ref: '#/components/parameters/Authorization'
      security:
        - API-Key: []
  
  /users/{userId}/roles:  
    get:  
      tags:
        - Users
      summary: List Roles Assigned to User  
      description: Retrieves a list of roles assigned to a specific user.  
      parameters:  
        - name: userId  
          in: path  
          description: ID of the user to retrieve assigned roles for  
          required: true  
          schema:  
            type: string  
      responses:
        '200':
          description: OK.
          $ref: '#/components/responses/SystemRoles'
        '401':
          $ref: '#/components/responses/errorUnauthenticated'
        "403":
          $ref: "#/components/responses/errorForbidden"
        '500':
          $ref: '#/components/responses/genericError'
      security:
        - API-Key: []

    post: 
      tags:
        - Users 
      summary: Assign Roles to User  
      description: Assigns list roles to a user.  
      parameters:  
        - name: userId  
          in: path  
          description: ID of the user to assign the role to  
          required: true  
          schema:  
            type: string
      requestBody:
        $ref: "#/components/requestBodies/RoleList"       
      responses:
        "201":
          description: OK.
          $ref: "#/components/responses/userRoleMixedResponse"
        "400":
          $ref: "#/components/responses/roleInvalidInput"
        "401":
          $ref: "#/components/responses/errorUnauthenticated"
        "403":
          $ref: "#/components/responses/errorForbidden"
        "409":
          $ref: "#/components/responses/roleAlreadyExists"
        "500":
          $ref: "#/components/responses/genericError"
      security:
        - API-Key: []

    delete:
      tags:
        - Users
      operationId: delete-user-roles
      summary: Delete user's roles by role ids
      description: Delete the roles assigned to a user using a list of role IDs. (Admin permissions required)
      parameters:
        - name: userId  
          in: path  
          description: The ID of the user whose roles are to be removed  
          required: true  
          schema:  
            type: string
      requestBody:
        $ref: "#/components/requestBodies/RoleList"       
      responses:
        "200":
          description: OK.
          $ref: "#/components/responses/userRoleMixedResponse"
        "400":
          $ref: "#/components/responses/roleInvalidInput"
        "401":
          $ref: "#/components/responses/errorUnauthenticated"
        "403":
          $ref: "#/components/responses/errorForbidden"
        "409":
          $ref: "#/components/responses/roleIsNotAssigned"
        "500":
          $ref: "#/components/responses/genericError"
      security:
        - API-Key: []

components:
  schemas:
    Authorizations:
      description: ''
      type: object
      x-examples:
        ExampleAuthorization:
          appUserId: b647517b-5883-4963-98cf-8726b3a2cf60
          userId: 871fb3e8-a3d3-423c-a709-9de92c15c9f7
          applicationId: d6b80eb2-90eb-4820-b2ba-b0a19824c532
          groupPermissions:
            2f87320e-f2fc-4c49-83f0-6ff3e561937a:
              - ie.software.runtime.api.app.uninstall
              - ie.software.runtime.api.app.logs.download
          role: User
          ResourceId: b647517b-5883-4963-98cf-8726b3a2cf60
          ResourceType: User
          AppPermissions: []
        ExampleAppAuthorization:
          appUserId: b647517b-5883-4963-98cf-8726b3a2cf60
          userId: 871fb3e8-a3d3-423c-a709-9de92c15c9f7
          applicationId: d6b80eb2-90eb-4820-b2ba-b0a19824c532
          role: User
          ResourceId: b647517b-5883-4963-98cf-8726b3a2cf60
          ResourceType: Application
          AppPermissions:
            - ie.software.runtime.api.app.uninstall - ie.software.runtime.api.app.logs.download
      title: ''
      properties:
        appUserId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        applicationId:
          type: string
          format: uuid
          description: Maps to the application for which the authorization is required.
        groupPermissions:
          type: object
          description: This property is a map where the key - is a string corresponding to groupId (uuid) and value - is an array of strings corresponding to the list of group permissions.
        role:
          type: string
          minLength: 1
          description: 'Possible values: Admin OR User'
        resourceId:
          type: string
          format: uuid
          description: 'Possible values: appUserId or appId.'
        resourceType:
          type: string
          description: 'Possible values: Application OR User'
        appPermissions:
          type: object
          description: This property is array where app permission are stored in form of string.
    errors.generic:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: "0x00000001"
              status:
                type: integer
                example: 500
              title:
                type: string
                example: "Internal Server Error"
              correlationId:
                type: string
              source:
                type: object
                description: Optional or will have one of the following members
                properties:
                  parameter:
                    type: string
                    description: a string that indicates which URI query parameter caused the error.
                  pointer:
                    type: string
                    description: JSON pointer to the value in the request document that caused the error. Example, "/data" for a primary data object, or "/data/attributes/title" for a specific attribute.
                  header:
                    type: string
                    description: a string that indicates the name of a the header property which caused the error.
                  resourceId:
                    type: string
                    description: a string that indicates the id of the resource which caused the error.
    Error:
      description: Error consist of code which is associated with message and logref which is a uuid, used to distincly identify the error.
      type: object
      x-examples:
        ExampleError:
          code: auth.application.notFound
          logref: c105072b-39cb-49d9-999f-3873b10e3db1
          message: Application not found.
      properties:
        code:
          type: string
          minLength: 1
        logref:
          type: string
          minLength: 1
          format: uuid
          description: Unique uuid generated for each error
        message:
          type: string
          minLength: 1
      required:
        - code
        - message
    ErrorResponse:
      description: |-
        - The Error response is list of errors.
        - The errors if present more than one is sent in succession. 
        - Array of errors returns all error at once, rather than sending them sepearately.
      type: object
      x-examples:
        ExampleErrorList:
          errors:
            - code: auth.application.notFound
              logref: c105072b-39cb-49d9-999f-3873b10e3db1
              message: Application not found.
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    SystemRoleCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Unique role name, defined by client (for easier usage)
          example: "role-name"
        description:
          type: string
          description: Role description
          example: "role-description"
    SystemRoleId:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Internal prompt identifier, generated by the Auth service
          example: "ce96f954-a9c9-4b29-9ee9-23aa4775f77e"
    SystemRole:
      description: Used in the response of the method which fetches list of Roles.
      type: object
      x-examples:
        ExampleRole:
          id: 7382d58e-652a-4905-b7c9-bcca1e0e5391
          name: Admin
          description: Admin role      
      allOf:
        - $ref: "#/components/schemas/SystemRoleCreate"
        - $ref: "#/components/schemas/SystemRoleId"

  requestBodies:
    SystemRole:
      description: Single role.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SystemRoleCreate"
    RoleList:
      description: List of roles to be used by the operation.
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              roles:
                type: array
                items:
                  $ref: '#/components/schemas/SystemRoleId'
          example:
            roles:
            - id: 6ea7d6ca-d388-4480-8e6f-0a37e2a3ccad
            - id: de504955-9f38-489f-b8fb-c744ee3d6190
            - id: ce96f954-a9c9-4b29-9ee9-23aa4775f77e
  responses:
    SystemRole:
      description: Single role.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SystemRole"
    SystemRoles:
      description: List of roles.
      content:
        application/json:
          schema:
            type: object
            properties:
              roles:
                type: array
                items:
                  $ref: '#/components/schemas/SystemRole'
          examples:
            SystemRoles:
              value:
                roles:
                  - id: 6ea7d6ca-d388-4480-8e6f-0a37e2a3ccad
                    name: Admin
                    description: Admin role
                  - id: de504955-9f38-489f-b8fb-c744ee3d6190
                    name: User
                    description: User role
    userRoleMixedResponse:
      description: Mixed Response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/SystemRoleId'
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/errors.generic'
          examples:
            Partial success:
              value:
                data:
                  - id: 6ea7d6ca-d388-4480-8e6f-0a37e2a3ccad
                  - id: de504955-9f38-489f-b8fb-c744ee3d6190
                errors:
                  - code: "notFound"
                    status: 404
                    title: Role not found
                    correlationId: ppsshhd-64jsrtd-srtrhsdf-34232
                    source:
                      resourceId: ce96f954-a9c9-4b29-9ee9-23aa4775f77e
            None of the roles found:
              value:
                errors:
                  - code: "notFound"
                    status: 404
                    title: Role not found
                    correlationId: ppsshhd-64jsrtd-srtrhsdf-34232
                    source:
                      resourceId: ce96f954-a9c9-4b29-9ee9-23aa4775f77e
                  - code: "notFound"
                    status: 404
                    title: Role not found
                    correlationId: ppsshhd-64jsrtd-srtrhsdf-34232
                    source:
                      resourceId: as66f954-a9c9-4b29-9ee9-23aa4775f33w

    roleInvalidInput:
      description: Invalid input for role
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            Invalid User Id:
              value:
                errors:
                  - code: "request.invalidObject"
                    status: 400
                    title: User not found
                    correlationId: kkjsjjd-38jsjd-sjdhsdf-37738
                    source:
                      parameter: userId
            Invalid Body:
              value:
                errors:
                  - code: "request.invalidObject"
                    status: 400
                    title: Invalid body request data
                    correlationId: kkjsjjd-38jsjd-sjdhsdf-37738
                    source:
                      pointer: body
    roleAlreadyExists:
      description: Role already assigned
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            errors:
              - code: "alreadyExists"
                status: 409
                title: Role already assigned
                correlationId: ppsshhd-64jsrtd-srtrhsdf-34232
    roleIsNotAssigned:
      description: Role is not assigned
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            errors:
              - code: "assignmentDoesNotExists"
                status: 409
                title: Role assignment doesn't exist
                correlationId: ppsshhd-64jsrtd-srtrhsdf-34232

    errorUnauthenticated:
      description: Unauthenticated, authorization token does not exists or not starting with bearer <auth token>
      content:
        application-json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing-auth-header:
              value:
                errors:
                  - code: "auth.missingToken"
                    status: 401
                    title: Authentication Token is missing
            invalid-auth-header:
              value:
                errors:
                  - code: "auth.unauthenticated"
                    status: 401
                    title: Authentication Token is invalid
    TokenError:
      description: |-
        Unauthorized:
        - Missing the auth token
        - Invalid auth token
        - Expired auth token
        - User of the auth token was not found
        - Unable to verify auth token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            MissingTokenError:
              $ref: '#/components/examples/MissingToken'
            InvalidTokenError:
              $ref: '#/components/examples/InvalidToken'
            ExpiredTokenError:
              $ref: '#/components/examples/ExpiredToken'
            TokenUserNotFoundError:
              $ref: '#/components/examples/TokenUserNotFound'
            UnableToVerifyToken:
              $ref: '#/components/examples/UnableToVerifyToken'
    genericError:
      description: Something went wrong
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors.generic"
    errorForbidden:
      description: Unauthorized, the user doesn't have the role or the privileges to execute the action. Access denied.
      content:
        application-json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized-token:
              value:
                errors:
                  - code: "auth.unauthorizedToken"
                    status: 403
                    title: Not enough privileges to perform this action
    roleNotFoundError:
      description: Role not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - code: "notFound"
                status: 404
                title: failed to find object, role with id:RoleId
                correlationId: 459a074d-69d3-4326-b92a-e017d3f8585d

  parameters:
    roleId:
      in: path
      name: name
      example: "role-id"
      required: true
      schema:
        type: string
      description: The unique role id, defined in get roles list
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: Authorization token
    X-Correlation-ID:
      name: X-Correlation-ID
      in: header
      required: false
      schema:
        type: string
      description: Correlates logs
  examples:
    MissingToken:
      value:
        errors:
          - code: edge.auth.missingToken
            message: Token is required.
            logref: 3505f6bd-30cd-4deb-981d-02e89f82aa8f
    InvalidQueryParams:
      value:
        errors:
          - code: edge.application.invalidQueryParams
            message: Unable to parse query params.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    InvalidToken:
      value:
        errors:
          - code: edge.auth.invalidToken
            message: Token is invalid.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    ExpiredToken:
      value:
        errors:
          - code: edge.auth.expiredToken
            message: Token expired.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    TokenUserNotFound:
      value:
        errors:
          - code: auth.application.userNotFound
            message: User not found.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    UnableToVerifyToken:
      value:
        errors:
          - code: auth.token.unableToVerifyToken
            message: Unable to verify token.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    UnableToParseFormData:
      value:
        errors:
          - code: edge.unableToParseFormData
            message: Invalid requested form data provided.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    
    NotPermitted:
      value:
        errors:
          - code: auth.notPermitted
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Access denied.
    
    
    InternalServerError:
      value:
        errors:
          - code: auth.internalServerError
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: The server encountered an unknown error.
    
    InvalidPermissionList:
      value:
        errors:
          - code: auth.permission.invalidList
            message: 'The following permissionId are invalid:'
            logref: 7e8643f3-ac27-4448-ae2e-3bd68b092b01
    
  securitySchemes:
    API-Key:
      name: Authorization
      type: apiKey
      in: header