openapi: 3.0.0
info:
  title: IED OpenID Connect Provider APIs
  version: '1.0'
  description: IED OpenID Connect Provider API documentation. The specification is compatible starting from version 1.14 of IE Runtime.
  contact:
    name: Team ADI
  license:
    name: 'Industrial Edge © 2023, Siemens AG. All rights reserved.'
servers:
  - url: 'https://localhost/device/edge/auth/api/v1'
tags:
  - name: oidc-providers
    description: Edge auth service OIDC endpoint. (OIDC Clients can be configured to connect to identity providers to validate the user identity)
paths:
  '/oidc-providers':
    get:
      summary: List OIDC Client Configs
      responses:
        '200':
          description: |-
            OK: Successfully retrieved list of oidc client configs.
            If queryparam detailed is true, then list will contain all details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  OidcConfigList:
                    type: array
                    items:
                      $ref: '#/components/schemas/OidcConfig'
              examples:
                OidcDetailedConfigList:
                  value:
                    oidcConfigList:
                      - oidcId: 1fc86671-af95-4959-a294-caf166b46cfd
                        oidcName: IDP1
                        oidcClientId: device121
                        oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                        oidcScopes: openid email profile
                        oidcRedirectHost: 'https://127.0.0.1'
                        createdDate: 1644990539
                        modifiedDate: 1644990539
                      - oidcId: oi2jge33-bl88-4628-f1b4-cafa34b26anu
                        oidcName: IDP2
                        oidcClientId: device123
                        oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                        oidcScopes: openid email profile
                        oidcRedirectHost: 'https://127.0.0.1'
                        createdDate: 1644990561
                        modifiedDate: 1644990561
                OidcConfigList:
                  value:
                    oidcConfigList:
                      - oidcName: IDP1
                        oidcClientId: device121
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidQueryParams:
                  $ref: '#/components/examples/InvalidQueryParams'
        '401':
          $ref: '#/components/responses/TokenError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.failedToListConfig:
                  $ref: '#/components/examples/OidcFailedToList'
      description: |-
        This method fetches the list of configured oidc client configs
        With the queryparam detailed set to true, the returned objects will contain all information. 
        For this operation admin rigths are needed. 
        With this param set to false, it will only contain name and id.
      operationId: get-oidc
      tags:
        - oidc-providers
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
        - schema:
            type: boolean
            default: false
          in: query
          name: detailed
          description: Returns a detailed list of the registered OIDC providers.
          required: false
    post:
      summary: Create OIDC Client Config
      responses:
        '200':
          description: 'OK: Successfully created the new Oidc Client Config.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OidcConfigCreate'
              examples:
                OidcConfigCreate:
                  value:
                    oidcName: IDP1
                    oidcClientId: device123
                    oidcClientSecret: 8efd6f5029334011adb8702f7def0ef7
                    oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                    oidcScopes: openid email profile
                    oidcRedirectHost: 'https://127.0.0.1'
        '400':
          description: 'Bad Request: Unable to parse body data send through request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.unableToParseBodyData:
                  $ref: '#/components/examples/UnableToParseFormData'
        '401':
          $ref: '#/components/responses/TokenError'
        '500':
          description: 'Internal Server Error: '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.configNotCreated:
                  $ref: '#/components/examples/OidcConfigNotCreated'
      description: |
        This methods is used to create a new oidc client config to connect to an external identity provider.
      operationId: post-oidc
      tags:
        - oidc-providers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OidcConfig'
            examples:
              OidcConfig:
                value:
                  oidcName: IDP1
                  oidcClientId: device121
                  oidcClientSecret: 8efd6f5029334011adb8702f7def0ef7
                  oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                  oidcScopes: openid email profile
                  oidcRedirectHost: 'https://127.0.0.1'
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
  '/oidc-providers/{oidcId}':
    parameters:
      - schema:
          type: string
          format: uuid
        name: oidcId
        in: path
        required: true
        description: Maps to a oidc config
    put:
      summary: Edit OIDC Client Config by OidcId
      responses:
        '200':
          description: |-
            OK: Successfully updated oidc client config.
            returns the updated object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OidcConfigCreate'
              examples:
                OidcConfigCreate:
                  value:
                    oidcName: IDP1
                    oidcClientId: device123
                    oidcClientSecret: 8efd6f5029334011adb8702f7def0ef7
                    oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                    oidcScopes: openid email profile
                    oidcRedirectHost: 'https://127.0.0.1'
        '400':
          description: 'Bad Request  '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.invalidId:
                  $ref: '#/components/examples/OidcInvalidId'
                auth.unableToParseBodyData:
                  $ref: '#/components/examples/UnableToParseFormData'
        '401':
          $ref: '#/components/responses/TokenError'
        '404':
          description: Failed to edit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.configNotFound:
                  $ref: '#/components/examples/OidcConfigNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.failedToUpdateConfig:
                  $ref: '#/components/examples/OidcFailedToUpdate'
      description: '- This method is used to edit a oidc client config'
      operationId: edit-oidc-oidcid
      tags:
        - oidc-providers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OidcConfig'
            examples:
              OidcConfig:
                value:
                  oidcName: IDP1
                  oidcClientId: device121
                  oidcClientSecret: 8efd6f5029334011adb8702f7def0ef7
                  oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                  oidcScopes: openid email profile
                  oidcRedirectHost: 'https://127.0.0.1'
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
    get:
      summary: Get Details of OIDC Client Config
      responses:
        '200':
          description: 'OK: Successfully returns Oidc Client Config details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OidcConfig'
              examples:
                OidcConfig:
                  value:
                    oidcId: 1fc86671-af95-4959-a294-caf166b46cfd
                    oidcName: IDP1
                    oidcClientId: device121
                    oidcIssuer: 'https://auth.example.com/auth/realms/customer'
                    oidcScopes: openid email profile
                    oidcRedirectHost: 'https://127.0.0.1'
                    createdDate: 1644990539
                    modifiedDate: 1644990539
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.invalidId:
                  $ref: '#/components/examples/OidcInvalidId'
        '401':
          $ref: '#/components/responses/TokenError'
        '404':
          description: 'Not Found: The oidc config in the request was not found.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.configNotFound:
                  $ref: '#/components/examples/OidcConfigNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: |-
        This method returns the details of a particular oidc client config. 
        - Specify the required oidc client config using the `oidcId` path parameter.
      operationId: get-oidc-oidcid
      tags:
        - oidc-providers
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
    delete:
      summary: Delete a OIDC Client Config
      responses:
        '204':
          description: 'No Content: oidc config successfully deleted.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.invalidId:
                  $ref: '#/components/examples/OidcInvalidId'
        '401':
          $ref: '#/components/responses/TokenError'
        '404':
          description: 'Not Found: The oidc config in your request was not found.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.configNotFound:
                  $ref: '#/components/examples/OidcConfigNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnableToDeleteOidcConfig:
                  $ref: '#/components/examples/OidcFailedToUpdate'
      description: |-
        This method deletes a particular oidc config.

        - Specify the oidc config to be deleted using the `oidcId` path parameter.
      operationId: delete-oidc-oidcid
      tags:
        - oidc-providers
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
  '/oidc-providers/{oidcId}/login':
    parameters:
      - schema:
          type: string
          format: uuid
        name: oidcId
        in: path
        required: true
        description: Maps to a oidc config
    post:
      summary: Login Route for IdP
      operationId: post-oidc-login
      responses:
        '204':
          description: 'No Content: successful redirection'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.missingOidcId:
                  $ref: '#/components/examples/OidcMissingId'
                oidc.invalidId:
                  $ref: '#/components/examples/OidcInvalidId'
        '408':
          description: Identity provider unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oidc.unreachable:
                  $ref: '#/components/examples/OidcIdPUnreachable'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: '- This method creates a client connection to idp and redirects to it'
      parameters:
        - $ref: '#/components/parameters/X-Correlation-ID'
      tags:
        - oidc-providers
  '/oidc-providers/callback':
    parameters:
      - schema:
          type: string
        name: state
        in: header
        description: Secure cookie with encrypted state
      - schema:
          type: string
        name: state
        in: query
        description: State parameter matching the secure cookie
      - schema:
          type: string
        name: session_state
        in: query
        description: Session state as used by Oauth2
      - schema:
          type: string
        name: code
        in: query
        description: Code as used by Oauth2
    get:
      summary: Redirect URL for Identiy Provider
      responses:
        '302':
          description: Redirect to main page on /device/edge
        '400':
          description: Missing or invalid state parameter
        '401':
          description: User not authorized
      description: |-
        This method is called after the successul login on the Identiy Provider. 
        It tries to log in the user into the system and redirects to the start page when successful
      operationId: get-oidc-callback
      tags:
        - oidc-providers
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
  '/oidc-providers/config':
    get:
      summary: Retrieve OIDC API configuration
      responses:
        '200':
          description: |- 
            OK: Successfully retrieved OIDC API configuration
          content:
            application/json:
              schema:            
                $ref: "#/components/schemas/OidcSettings"     
              examples:
                OidcGlobalConfig:
                  $ref: "#/components/schemas/OidcSettings"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidTokenError:
                  $ref: '#/components/examples/InvalidTokenError'
                MissingTokenError:
                  $ref: '#/components/examples/MissingToken'
                ExpiredTokenError:
                  $ref: '#/components/examples/ExpiredToken'
                UnableToVerifyTokenError:
                  $ref: '#/components/examples/UnableToVerifyToken'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                OidcNotAuthorized:
                  $ref: '#/components/examples/OidcNotAuthorized'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
      tags:
        - oidc-providers
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'
    put:
      summary: Update OIDC API configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OidcSettings'
      responses:
        '204':
          description: |-
            OK: Successfully updated OIDC API configuration
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                edge.settings.oidcClockSkewOutOfRange:
                  $ref: '#/components/examples/OidcGlobalConfigOutOfRange'
                edge.unableToParseBodyData:
                  $ref: '#/components/examples/UnableToParseBodyData'
                edge.job.invalidRequestBody:
                  $ref: '#/components/examples/OidcGlobalConfigBadRequest'
                edge.settings.invalidOidcClockSkew:
                  $ref: '#/components/examples/OidcGlobalConfigInvalid'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidTokenError:
                  $ref: '#/components/examples/InvalidTokenError'
                MissingTokenError:
                  $ref: '#/components/examples/MissingToken'
                ExpiredTokenError:
                  $ref: '#/components/examples/ExpiredToken'
                UnableToVerifyTokenError:
                  $ref: '#/components/examples/UnableToVerifyToken'                
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                OidcNotAuthorized:
                  $ref: '#/components/examples/OidcNotAuthorized'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
      tags:
        - oidc-providers
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/X-Correlation-ID'

components:
  schemas:
    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'
    OidcConfigCreate:
      description: Config Object to configure OIDC Client
      type: object
      properties:
        oidcId:
          type: string
        oidcName:
          type: string
        oidcClientId:
          type: string
        oidcClientSecret:
          type: string
        oidcIssuer:
          type: string
        scopes:
          type: string
        oidcRedirectHost:
          type: string
      required:
        - oidcName
        - oidcClientId
        - oidcClientSecret
        - oidcIssuer
        - oidcRedirectHost
      x-examples:
        OidcConfigCreate:
          - oidcName: IDP1
            oidcClientId: device123
            oidcClientSecret: 8efd6f5029334011adb8702f7def0ef7
            oidcIssuer: 'https://auth.example.com/auth/realms/customer'
            oidcScopes: openid email profile
            oidcRedirectHost: 'https://127.0.0.1'
    OidcConfig:
      description: Config Object returned for OIDC Clients
      type: object
      properties:
        oidcId:
          type: string
        oidcName:
          type: string
        oidcClientId:
          type: string
        oidcIssuer:
          type: string
        oidcScopes:
          type: string
        oidcRedirectHost:
          type: string
        createdDate:
          type: number
        modifiedDate:
          type: number
      required:
        - oidcName
        - oidcClientId
      x-examples:
        OidcConfig:
          - oidcName: IDP1
            oidcClientId: device123
            oidcScopes: openid email profile
            oidcRedirectHost: 'https://127.0.0.1'
            createdDate: 1632494254000
            modifiedDate: 1637323567000
    OidcSettings:
      description: Config Object to configure global OIDC Settings
      type: object
      properties:
        oidcClockSkew:
          type: integer
          format: int
          description: The OIDC clock skew in miliseconds
          minimum: 0
          maximum: 60000
  responses:
    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'

  parameters:
    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:
    OidcConfigNotCreated:
      value:
        errors:
          - code: oidc.configNotCreated
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Unable to create OIDC Config.
    OidcFailedToList:
      value:
        errors:
          - code: oidc.failedToListConfig
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Failed to list OIDC config.
    OidcFailedToUpdate:
      value:
        errors:
          - code: oidc.failedToUpdateConfig
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Failed to update OIDC config.
    OidcConfigNotFound:
      value:
        errors:
          - code: oidc.configNotFound
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: OIDC config not found.
    OidcMissingId:
      value:
        errors:
          - code: oidc.missingOidcId
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: OIDC ID missing in the OIDC API request.
    OidcInvalidId:
      value:
        errors:
          - code: oidc.invalidId
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Invalid OIDC ID.
    OidcIdPUnreachable:
      value:
        errors:
          - code: oidc.unreachable
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Idp Provider unreachable
    UnableToParseFormData:
      value:
        errors:
          - code: edge.unableToParseFormData
            message: Invalid requested form data provided.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    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

    InvalidTokenError:
      value:
        errors:
          - code: auth.login.invalidAppToken
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Invalid Application token.
    InternalServerError:
      value:
        errors:
          - code: auth.internalServerError
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: The server encountered an unknown error.
    UnableToParseBodyData:
      value:
        errors:
          - code: edge.unableToParseBodyData
            message: Invalid request body supplied.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    OidcGlobalConfigBadRequest:
      value:
        errors:
          - code: edge.job.invalidRequestBody
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Invalid request body
    OidcGlobalConfigOutOfRange:
      value:
        errors:
          - code: edge.settings.oidcClockSkewOutOfRange
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: OIDC clock skew out of permitted range
    OidcGlobalConfigInvalid:
      value:
        errors:
          - code: edge.settings.invalidOidcClockSkew
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Invalid OIDC clock skew config.
    OidcNotAuthorized:
      value:
        errors:
          - code: edge.login.userNotAuthorized
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: User not Authorized.