swagger: "2.0"
info:
  title: "Login API"
  description: "Mit dieser API kann sich der Verwender an der Anwendung ein- und ausloggen. Beim Einloggen bekommt der Verwender zu einem Benutzernamen und einem Passwort ein JWT-Token, das für weitere Aufrufe von API-Funktionen verwendet werden kann."
  version: "2.0.0"
  contact:
    name: "innovas GmbH"
    email: "support-health@innovas.de"
basePath: /benutzer/api-extern/v2.0.0

securityDefinitions:
  jwt:
    type: apiKey
    in: header
    name: Cookie

security:
  - jwt: []

#libraryName und libraryNameClient werden nur intern bei der Innovas verwendet
x-libraryName: benutzersst
x-libraryNameClient: "@innovas/benutzersst-lib"

schemes:
  - https
consumes:
  - application/json
produces:
  - application/json

responses:
  unknownerror:
    description: "Unbekannter Fehler aufgetreten"
    schema:
      type: array
      minItems: 1
      items:
        $ref: "#/definitions/Meldung"

paths:
  /authenticate:
    post:
      summary: "Benutzer authentifizieren"
      security: []
      description: 'Benutzer wird per Benutzername und Passwort authentifiziert. Das JSON Web Token, das für weitere Aufrufe der Schnittstellen benötigt wird, wird als Cookie mit dem Cookienamen JWT_TOKEN zurückgeliefert. Der Cookie muss bei allen folgenden Aufrufen als Header mit dem Namen "Cookie" übertragen werden. Wie bei allen externen Schnittstellen muss der Header sec-maschineller-request übertragen werden. Da diese Schnittstelle in der Regel die erste aufgerufene Schnittstelle ist, wird für den Header der fixe Startwert "Startwert_Sec-Maschineller-Request" übertragen.'
      operationId: authenticate
      parameters:
        - name: "loginanfrage"
          in: "body"
          required: true
          description: "Benutzername und Passwort des Benutzers"
          schema:
            $ref: "#/definitions/LoginAnfrage"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/AuthContainer"
        401:
          description: "Authentifizierung fehlgeschlagen, weil Benutzername oder Passwort falsch sind"
        500:
          $ref: "#/responses/unknownerror"

  /authenticate/tan:
    post:
      summary: "Benutzer authentifizieren mit TAN"
      security: []
      description: "Benutzer wird per TAN authentifiziert. Wird nur verwendet, wenn die 2-Faktor-Authentifizierung per TAN aktiviert ist. Vor diesem Aufruf muss zunächst der Benutzer per Benutzername und Passwort authentifiziert werden um eine TAN an den Benutzer zu versenden und das dort zurückgegegeben TanToken muss hier übergeben werden."
      operationId: authenticateWithTan
      parameters:
        - name: "relogin"
          in: "query"
          required: false
          type: boolean
        - name: "loginanfrage"
          in: "body"
          required: true
          schema:
            $ref: "#/definitions/LoginAnfrageMitTan"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/AuthContainer"
        401:
          description: "Authentifizierung fehlgeschlagen, weil die TAN falsch ist"
        500:
          $ref: "#/responses/unknownerror"

  /checktoken:
    post:
      summary: "Prüfe Token"
      description: "Prüfe Token und gibt im Erfolgsfall den Benutzer zurück"
      operationId: checkToken
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/BenutzerAnmeldung"
        401:
          description: "Pruefung fehlgeschlagen"
        500:
          $ref: "#/responses/unknownerror"

  /logout:
    post:
      summary: "Benutzer ausloggen"
      description: "Benutzer wird abgemeldet"
      operationId: logout
      responses:
        204:
          description: "successful operation"
        401:
          description: "Authentifizierung fehlgeschlagen."
        500:
          $ref: "#/responses/unknownerror"

definitions:
  BenutzerBasis:
    type: object
    required:
      - username
      - vorname
      - nachname
    properties:
      username:
        type: string
        minLength: 1
        maxLength: 254
        description: "Benutzername des Benutzers"
      vorname:
        type: string
        minLength: 1
        maxLength: 40
        description: "Vorname des Benutzers"
      nachname:
        type: string
        minLength: 1
        maxLength: 40
        description: "Nachname des Benutzers"
      email:
        type: string
        minLength: 1
        maxLength: 254
        description: "E-Mail-Adresse des Benutzers"
      telefonNr:
        type: string
        minLength: 8
        maxLength: 32
        description: "Telefon-Nr. des Benutzers"
      telefonnummerZweiFaktorAuth:
        type: string
        minLength: 8
        maxLength: 32
        description: "Telefon-Nr. des Benutzers für die Zwei-Faktor-Authentifizierung"
      fax:
        type: string
        minLength: 8
        maxLength: 32
        description: "Fax-Nr. des Benutzers"
      aktivFlag:
        type: boolean
        description: "Zeigt ob der Benutzer aktiv/inaktiv geschaltet ist"

  Benutzer:
    allOf:
      - $ref: "#/definitions/BenutzerBasis"
      - properties:
          organisationseinheit:
            $ref: "#/definitions/Organisationseinheit"
          rollen:
            type: array
            items:
              $ref: "#/definitions/Rolle"
          gesperrt:
            type: boolean
        required:
          - organisationseinheit
          - rollen
          - gesperrt

  Organisationseinheit:
    type: object
    required:
      - fachId
      - name
    properties:
      fachId:
        type: string
        minLength: 1
        maxLength: 64
        description: "Fachliche ID der Organisationseinheit"
      name:
        type: string
        minLength: 1
        maxLength: 64
        description: "Name der Organisationseinheit"
      erlaubteRollen:
        type: array
        items:
          type: string
          minLength: 1
          maxLength: 25
          description: "Fachliche ID der Rolle"
      unterOrganisationseinheiten:
        type: array
        items:
          $ref: "#/definitions/Organisationseinheit"

  Rolle:
    type: object
    required:
      - fachId
      - name
    properties:
      fachId:
        type: string
        minLength: 1
        maxLength: 25
        description: "Fachliche ID der Rolle"
      name:
        type: string
        minLength: 1
        maxLength: 25
        description: "Name der Rolle"
      erlaeuterung:
        type: string
        minLength: 0
        maxLength: 200
        description: "Erläuterung"

  LoginAnfrage:
    type: object
    required:
      - username
      - password
    properties:
      username:
        type: string
        minLength: 1
        maxLength: 254
        description: "Benutzername des Benutzers"
      password:
        type: string
        minLength: 0
        maxLength: 40
        description: "Passwort des Benutzers"

  LoginAnfrageMitTan:
    type: object
    description: "Loginanfrage mit TAN für Zwei-Faktor-Authentifizierung"
    allOf:
      - $ref: "#/definitions/LoginAnfrage"
      - properties:
          tan:
            type: string
            minLength: 6
            maxLength: 6
            description: "TAN für Zwei-Faktor-Authentifizierung"
          tanToken:
            $ref: "#/definitions/TanToken"
        required:
          - tan
          - tanToken

  AuthContainer:
    type: object
    properties:
      benutzerAnmeldung:
        $ref: "#/definitions/BenutzerAnmeldung"
      forcedPwdChange:
        type: boolean
        description: "Angabe, ob das Passwort nach der Anmeldung geändert werden muss. Wenn der Wert nicht angegeben ist, ist eine Passwortänderung nicht notwendig."
      telefonNr:
        type: string
        minLength: 1
        maxLength: 32
        description: "Telefon-Nr. des Benutzers, zur Anzeige der Nummer an die die TAN geschickt wurde"
      tanToken:
        $ref: "#/definitions/TanToken"
    required:
      - benutzerAnmeldung

  BenutzerAnmeldung:
    type: object
    properties:
      benutzer:
        $ref: "#/definitions/Benutzer"
      ablaufAnmeldung:
        type: string
        format: date-time
        description: "Zeitpunkt des Ablaufs der Anmeldung"
    required:
      - benutzer
      - ablaufAnmeldung

  TanToken:
    type: string
    maxLength: 1200
    description: "JSON Web Token, welches u.a die TAN für die Zwei-Faktor-Authentifizierung beinhaltet. Wird nur für Benutzer mit aktivierter 2-Faktor-Authentifizierung verwendet"

  Meldungslevel:
    description: Ein Fehler gibt an, dass die Aktion nicht ausgeführt wurde. Eine Warnung gibt an, dass die Aktion nicht durchgeführt wurde, aber der Verwender die Aktion durch nochmalige explizite Bestätigung durchführen kann. Ein Hinweis gibt an, dass die Aktion (ggf. leicht abweichend) ausgeführt wurde.
    type: string
    enum:
      - Hinweis
      - Warnung
      - Fehler
  Meldung:
    type: object
    required:
      - level
      - text
    properties:
      level:
        $ref: "#/definitions/Meldungslevel"
      code:
        type: string
        description: "Fehlercode"
        maxLength: 8
      text:
        type: string
        description: "Fehlermeldung"
      feldliste:
        type: array
        description: "Optionale Liste der Felder, auf die sich die Fehlermeldung bezieht"
        items:
          type: string
          description: 'Ein Feld wird identifiziert über den voll qualifizierten Pfad des Eingabeobjektes der API-Methode, die den Fehler ausgelöst hat, wobei die Bestandteile jeweils durch "." getrennt sind. Bei Arrays wird das i-te Objekt durch "[i]" referenziert.'
