openapi changes

serviceAPIs/queryAPI.yaml

@@ -25,6 +25,8 @@ tags:
     description: Operations related to queries
   - name: ExportService
     description: Operations related to exports
+  - name: AuthService
+    description: Operations related to authentication
 
 paths:
   /client:
@@ -494,6 +496,151 @@ paths:
         "500":
           $ref: "#/components/responses/InternalError"
 
+
+  /login:
+    get:
+      operationId: login
+      tags:
+        - AuthService
+      summary: Login to the application
+      description: >-
+        Initiates the login flow by redirecting to Cognito IDP login page.
+      security:
+        - {}
+        - cognitoAuth: [openid, email, profile]
+      responses:
+        "302":
+          description: Redirect to Cognito login page
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+                maxLength: 2048
+                pattern: "^https://.*"
+              description: URL to the Cognito login page
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /login-callback:
+    get:
+      operationId: loginCallback
+      tags:
+        - AuthService
+      summary: OAuth2 callback endpoint
+      description: >-
+        Handles the OAuth2 callback during the login process. Receives the
+        authorization code from Cognito IDP and exchanges it for tokens.
+      security:
+        - {}
+      parameters:
+        - name: code
+          in: query
+          description: Authorization code from Cognito
+          required: true
+          schema:
+            type: string
+            maxLength: 2048
+            pattern: "^[A-Za-z0-9\\-_]+$"
+        - name: state
+          in: query
+          description: State parameter for CSRF protection
+          required: true
+          schema:
+            type: string
+            maxLength: 1024
+            pattern: "^[A-Za-z0-9\\-_]+$"
+      responses:
+        "302":
+          description: Redirect to application after successful login
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+                maxLength: 2048
+                pattern: "^https?://.*"
+              description: URL to redirect after successful login
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /logout:
+    get:
+      operationId: logout
+      tags:
+        - AuthService
+      summary: Logout from the application
+      description: >-
+        Logs the user out by invalidating the session and redirecting to
+        Cognito logout endpoint.
+      security:
+        - placeholderAuth: []
+      responses:
+        "302":
+          description: Redirect to Cognito logout page or application home page
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+                maxLength: 2048
+                pattern: "^https?://.*"
+              description: URL to redirect after logout
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /home:
+    get:
+      operationId: getHomePage
+      tags:
+        - AuthService
+      summary: Get the home page menu
+      description: >-
+        Returns the HTML menu page for authenticated users.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Home page HTML
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            text/html:
+              schema:
+                type: string
+                description: HTML content for the home page menu
+                maxLength: 1048576  # 1MB limit
+                pattern: "^.*$"     # Any string content
+                format: html        # Indicate format is HTML
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
 components:
   parameters:
     ClientID:
@@ -544,6 +691,21 @@ components:
       in: header
       name: X-API-Key
       description: "Placeholder security scheme for future implementation"
+    cognitoAuth:
+      type: oauth2
+      description: >-
+        Authentication using Amazon Cognito IDP. Implements RFC8725 JWT best
+        practices for security.
+      flows:
+        authorizationCode:
+          authorizationUrl: >-
+            https://doczy.auth.us-east-1.amazoncognito.com/oauth2/authorize
+          tokenUrl: >-
+            https://doczy.auth.us-east-1.amazoncognito.com/oauth2/token
+          scopes:
+            openid: Get OIDC token
+            email: Access to user's email
+            profile: Access to user's profile
 
   responses:
     InvalidRequest:
@@ -595,6 +757,9 @@ components:
             $ref: "#/components/schemas/ErrorMessage"
 
   schemas:
+
+
+    # Query API schemas
     ClientID:
       type: string
       description: The client external id