With the help of the importer, resources, measures, controls and check questions for knowledge bases or structure updates for organizational units can be imported. These updates can come from an SAP export, for example, or from a specially created Excel or CSV file. In this way, obsolete structures can be updated or completely new structures can be imported.

If an import is performed, all entities that have been changed are updated, and all entities that do not yet exist in HITGuard are created.


== Performing an import ==

Imports can be performed only by administrators or experts.

To perform an import, first go to "Administration → Data import | Import logs". All created import configurations are now displayed here. To perform an import, either an existing import configuration is selected from the list or a new import configuration is created - the process is the same in both cases. Each import is documented under “Administration → Data Import → Import Logs”.

[[File:Org import 1.png|right|thumb|600px|Create a new import configuration]]
To use an existing import configuration, double-click the desired configuration. To create a new import configuration, click the plus button. (see figure)
 

[[File:Org import 2.png|right|thumb|600px|Select import type]]
A dialog box will then open (see image to the right) where you must enter the configuration name, select the configuration type, and upload the file to be imported.

The file can be either a CSV file or an Excel file. ([[Special:MyLanguage/Datenimport#Aufbau_einer_Importdatei|Structure of an import file]])
 

[[Datei:Importer Felder zuordnen.gif|right|thumb|600px|Assigning import fields]] Clicking on "Next" opens the mask for assigning the fields (see figure below). Here at least all mandatory fields of the selected import type should be assigned. You can find out what these are from the description of the individual imports.

If an Excel file is imported, care must be taken that column headings exist in the file. If these exist, it is selected that the first row contains column headers and should therefore be ignored.
 

[[Datei:Org import 4.png|right|thumb|601px|Save and import]]If all mandatory fields have now been assigned, the import can be saved and is ready for import. All that remains is to click on "Save and import".

Note: Instead of a username the name of a team can be entered for the field responsible, provided the team was already created in HITGuard. The name must be correct for the import to work. The team is then set as responsible, e.g., for a resource.
 

[[Datei:Org import 5.png|right|thumb|600px|Successful import message]] If the import was successful, you will see how many entities were newly created and how many were modified. In case of erroneous import operations, those rows and columns that contain errors will be listed for you.
 


== Import logs ==

[[Datei:Importprotokolle Übersicht.png|left|thumb|600px|List of import protocols]]
Each import attempt is documented under "Administration → Data import | Import logs". Both successful and failed import attempts are recorded.
 

[[Datei:Importprotokolle Detailansicht.png|left|thumb|600px|Import Protocol in Detail]]
By double-clicking on an import, you will be redirected to a screen where you can see details such as the reason why the import failed.
 


== Import data categories ==

To import data categories, the "Data category" type must be selected during import.

There are two options:
* Create new data categories
* Update existing data categories

Only classes created under Risk Management → Risk Policy → Data Classes are allowed for the Data Class field.

Only the values Yes and No are permitted for the fields Protection needs analysis and Person-related. You determine where the data categories can be used.

For information about responsible persons see [[#ver|User management]].


=== Create new data categories ===

When importing a file, HITGuard uses the data set ID in the import file to check whether it already exists anywhere in the HITGuard instance (system-wide) or not. If it does not exist, it is created again.

To create a new data category, you must fill in the mandatory fields
* Record ID ''(system-wide unique identifier)''
* Name
* Data class (as per the values in Risk Management → Risk policy → Data classes)
must be available and filled in. Only if this is the case, the import is feasible.

Furthermore the fields
* Description
* Parent record ID (parent data category) ''(unique identifier)''
* Protection needs analysis (Yes/No)
* Personal data (Yes/No)
can be assigned.

If the parent record ID is assigned to a data category, a data category with this ID must either already exist in HITGuard or be created in this import. Furthermore, no cycles may exist. Cycles are used when, for example, data category A has entered data category B as its parent ID and data category B has entered data category A as its parent ID. The importer detects these cycles, prevents the import and refers to the cycle error.


=== Update data categories ===

If the record ID of the data category is found during the import, no new data category is created, but the existing one is updated. That means: The existing fields of the import file update the already existing fields like e.g. designation, data class or person related. This allows the maintenance of individual data category or larger data category structures .

Example:
:It is decided to create a new data category that should be parent to already existing data categories. In this case, the already existing data categories can be easily subordinated to this new data category by changing their parent ID.

=== Template ===
*[[Media:Importvorlage_Datenkategorie.xlsx|Template: Importvorlage Datenkategorie.xlsx]]


== Import risks ==

To import risks, the "Risk" type is selected during import.

There are two options:
* Create new risk
* Update existing risks


=== Creation of new risks===

When importing a file, HITGuard uses the data set ID in the import file to check whether it already exists anywhere in the HITGuard instance (across management systems) or not. If it does not exist, it is created again.

To create a new risk, these required fields must be filled in
* Record ID (unique identifier across management systems)
* Name
* Responsible user (e.g., via username)

Additionally, the following fields can be assigned:
* Code
* Description
* Remarks
* Monetary impact
* Probability of occurrence
* Extent of damage
* Strategy
* Status
* Advisor

Other import tools in HITGuard specify the status using numbers. Here, however, you must enter the status as the exact word that appears in the drop-down menu in the “Status” field in the risk record (i.e., “Submitted,” “Active,” etc.). Be sure to use the correct capitalization—even minor discrepancies can prevent HITGuard from recognizing the status.

If the Damage Extent or Probability of Occurrence fields are assigned, then only content that matches the existing HITGuard classes is valid. Again, you must provide the exact word that are specified in the risk policy. For more information, see [[Special:MyLanguage/Risikopolitik#prob|Probabilities of occurrence]] or [[Special:MyLanguage/Risikopolitik#Schadensausmaße|Extensions of damage]].

If the field Strategy has been assigned, you must also ensure that a value is selected from the drop-down menu in the Strategy field under Risk. Furthermore, the restriction applies that only values that correspond to the assigned severity or benefit are permitted. Thus, for a severity, it must be a coping strategy, and for a benefit, it must be a treatment strategy.

Einem Risiko können zwar mehrere Personen als Sachbearbeiter zugewiesen werden, über den Import ist es aber nur möglich einen einzelnen Benutzer als Sachbearbeiter zuzuweisen.


=== Updating risks ===

If you enter the "External ID" of an existing Risk in the row "Record ID", no new Risk will be created. Instead, HITGUard will update the existing risk. The entries in the import file update the already existing fields such as designation, description, responsible person, etc. This enables the maintenance of individual risks.

Caution: The ID of the risk must be distinct across the entire HITGuard installation, it must not repeat in different management systems. If you, for example, import an risk with the ID 1234 into a management system, but in another management system there already is a risk with the ID 1234, then that risk will be overwritten.

=== Vorlage ===
* [[Medium:Importvorlage Risiko.xlsx|Importvorlage Risiko.xlsx]]


== Import business processes ==

To import business processes, the "Business process" type must be selected during import.

There are two options:
* Create new business processes
* Update existing business processes

For information about responsible persons see [[#ver|User management]].


=== Creation of new business processes ===

When importing a file, HITGuard checks whether a business process already exists or not based on the record ID in the import file. If none exists, the business process is created.

To create a new business process, you must fill in the mandatory fields
* Record ID ''(system-wide unique identifier)''
* Name
must be available and filled in. Only if this is the case, the import is possible.

Furthermore the fields
* Code
* Description
* Parent business process record ID ''(system-wide unique identifier)''
can be assigned.

If the parent business process record ID is assigned, a business process with this ID must either already exist in HITGuard or be created in this import.
Furthermore, no cycles may exist. Cycles exist if, for example, business process A has entered business process B as its parent ID and business process B has entered business process A as its parent ID. The importer recognizes these cycles, prevents the import and refers to the cycle error.


=== Update business processes ===

If the record ID of the organizational unit is found during the import, no new business process is created, but the existing one is updated. That means: The existing fields of the import file update the already existing fields like description, code, responsible person, or parent record ID. This enables the maintenance of individual business processes or business process structures.

Example:
:It is decided to create a new business process that is parent to already existing business processes. In this case, the already existing business processes can be subordinated to this new business process by changing their parent ID.

=== Template ===
*[[Media:Importvorlage_Geschäftsprozess.xlsx|Template: Importvorlage Geschäftsprozess.xlsx]]


== Import organizational units ==

To import organizational units, the "Organizational unit" type must be selected during import.

There are two options:
* Create new organizational structures
* Update existing organizational structures

For information about responsible persons see [[#ver|User management]].


=== Creation of new organizational units/structures ===

When importing a file, HITGuard uses the data set ID in the import file to check whether it already exists or not. If it does not exist, it is created again.

To create a new organizational unit, you must fill in the mandatory fields
* Record ID ''(system-wide unique identifier)''
* Name
must be available and filled in. Only if this is the case, the import is feasible.

Furthermore the fields
* Code
* Description
* Parent OU record ID ''(system-wide unique identifier)''
* Street
* Postal code
* City
* Country
* Sort order
can be assigned.

If the parent OU record ID is assigned, an organizational unit with this ID must either already exist in HITGuard or be created in this import. Furthermore, no cycles may exist. Cycles exist if, for example, organizational unit A has entered organizational unit B as its parent ID and organizational unit B has entered organizational unit A as its parent ID. The importer recognizes these cycles, prevents the import and refers to the cycle error.


=== Update organizational units/structures ===

If the record ID of the organizational unit is found during the import, no new organizational unit is created, but the existing one is updated. That means: The existing fields of the import file update the already existing fields like e.g. country, address or person in charge. This enables the maintenance of individual organizational units or larger organizational structures.

Example:
:It is decided to create a new department that is superior to already existing organizational units. In this case, the already existing organizational units can be subordinated to this new department by changing their parent ID.

=== Template ===
*[[Media:Importvorlage_OrgEh.xlsx|Template: Importvorlage OrgEh.xlsx]]


== Import measures ==

To import measures, the type "Measure" is selected upon importing.

There are two options:
* Create new measures
* Update existing measures


=== Creation of new measures ===

When importing a file, HITGuard uses the record ID in the import file to check whether it already exists or not. If it does not exist, it is created again.

To create a new measure, the following mandatory fields must be present and filled in:
*Code
*OrgUnit (external ID!)
*Name
*Responsible
*Recognized at
*Record ID
In addition, all prerequisites of the user administration apply if responsible persons are entered (see User administration).
Important: For the organizational unit you need to use its external ID. If you have not yet set this ID, you can do so manually before the import.

Furthermore, the following fields can be added optionally:
*State (0-6, see more information below)
*Description
*Remark
*Budgeted costs
*Actual costs
*Recognized on
*Start date
*Mentioned deadline - Caution: this is a mandatory field if you have configured it under Measures > Settings
*Deadline
*Finished on - Caution: may only be filled in if the measure is imported in the states Completed or Submitted
*Impact - with the names you defined under Measures > Settings
*Effort - with the names you defined under Measures > Settings
*Corrective measure (YES/NO)
*Improvement measure (YES/NO)
*Planned anew (YES/NO)
*Delayed (YES/NO)
*Risk reduction (YES/NO)
*KO-criterion (YES/NO)

The digits 0 to 6 are used for the state of the measure:
::{| class="wikitable"
!0
|Planned
|-
!1
|Open
|-
!2
|Suspended
|-
!3
|Completed (Caution: here the field Completed on must be filled in as well)
|-
!4
|Cancelled
|-
!5
|Submitted (here the field Completed on can be filled in)
|-
!6
|Rejected
|-
|}
Note: If you do not enter anything, state 1 (open) is used by default.


=== Update measures ===

If the record ID of the measure is found during the import, no new measure is created, but the existing one is updated. That is: the existing fields of the import file update the already existing fields.


=== Template ===

<div class="mw-translate-fuzzy">
*[[Media:Importvorlage_Maßnahmen.xlsx|Template: Importvorlage Maßnahmen.xlsx]]
</div>


== Import resources ==

To import resources, the "Resource" type is selected during import.

There are two options:
* Create new resources
* Update existing resources

For information about responsible persons see [[#ver|User management]].


=== Create new resources ===

When importing a file, HITGuard uses the record ID in the import file to check whether it already exists or not. If it does not exist, it is created again.

To create a new resource, you must fill in the mandatory fields
* Record ID ''(system-wide unique identifier)''
* and description
must be available and filled in. In addition, all prerequisites of the user administration apply if responsible persons are entered (see User administration).

Furthermore, the fields:
* Description
* model segment
* RTO
* and RPO
can be assigned. In the model segment, the following values are allowed: "Business Service Level", "Application Level", "IT Infrastructure Level", "OT Infrastructure Level", "Physical Security" and "Process Level". If the field is not assigned, the resources are assigned to the model segment "Application Level". RTO and RPO can be imported either as hours or as minutes; hours and minutes cannot be mixed. In that case, the minutes would overwrite the hours.Example: If I want an RTO of two and a half hours, I can either enter 2.5 hours or 150 minutes. If I enter 2 hours and 30 minutes, only the 30 minutes will be imported.Caution: When mapping the columns you also need to differentiate and decide between hours and minutes. If the field for minutes is available, it will be chosen over the hours, even if it is empty.
[[Datei:Detailansicht_RTORPO_Spaltenzuordnung.png|thumb|900px|left]] 


=== Update resources ===

If the record ID of the resource is found during the import, no new resource is created, but the existing one is updated. That is: the existing fields of the import file update the already existing fields.


=== Template ===

<div class="mw-translate-fuzzy">
*[[Media:Importvorlage_Ressourcen.xlsx|Template: Importvorlage Ressource.xlsx]]
</div>


==Import resource connection==

To import resource connections (meaning an edge, a dependency relationship between two structural elements), the "Resource connection" type is selected during import.
There are two options:
* Create new resource connections
* Update existing resource connections


===Create new resource connections===

To create a new resource connection, the mandatory fields
* External ID of the source ''(system-wide unique identification)''
* External ID of the target ''(system-wide unique identification)''
* Type source
* Type target
must be present and filled in.

Furthermore, the fields:
* Protection target and
* Dependency weighting
can be assigned.

Connections can be created between different resources, between organizational units and resources, processes and resources, data categories and resources, and suppliers and resources, in both directions.

The following rules apply in the assigning and weighing of protection targets:
* Neither protection target nor dependency weighting stated: all protection targets of the management system are created with 100%.
* Only protection target: the named protection target is created with a weighting of 100%.
* Only dependency weighting: all protection targets of the management system are created with this weighting.
* Protection target and dependency weighting: the named protection target is created with this weighting.

Note: If there already exists a connection created from a protection needs analysis, the new connection is imported but the connection from the protection needs analysis is not overwritten. If you delete the protection needs analysis, the imported connection becomes visible.
Note: If there are multiple entries with the same external ID source and external ID target and the same protection target, the last entry is always considered. 
::Example: 
::Row 1: Source_1, Target_1, resource, resource → sets all protection targets to 100%
::Row 2: Source_1, Target_1, resource, resource, confidentiality, 50 → sets the protection target "confidentiality" to 50%
::Result sof the import → confidentiality is 50%, all other protection targets are 100% for the connection between Source_1 and Target_1.


===Update resource connections===

If during the import the external ID of the source and the target are found in the same combination, no new resource connection is created but the existing one is updated instead. This means: the existing fields of the import file update the already existing fields.
Here, too, edges from protection needs analyses are not overwritten.


===Template===

<div class="mw-translate-fuzzy">
*[[Medium:Importvorlage_Ressourcenverbindung.xlsx|Import template resource connection.xlsx]]
</div>


==Import suppliers==

To import suppliers, the "Supplier" type is selected during import.

There are two options:
* Create new suppliers
* Update existing suppliers


===Create new suppliers===

When importing a file, HITGuard uses the record ID in the import file to check whether it already exists anywhere in the HITGuard instance (across management systems) or not. If it does not exist, it is created again.

To create a new resource, you must fill in the mandatory fields
*Record ID (unique identifier across management systems)
*Name.
Only if this is the case, the file can be imported.

Furthermore, the fields
*Code
*Expiration date
*Deactivated (x for yes, empty for no; true/false)
*External metric
*Justification
*Street
*Post code
*City
*County
*Country
*E-mail
*Telephone
*Homepage
can be present and filled in.


===Update suppliers===

If the record ID of the supplier is found during the import, no new supplier is created, but the existing one is updated. That means: The existing fields of the import file update the already existing fields such as name, description, expiration date, etc. This enables the maintenance of individual suppliers.


===Template===

<div class="mw-translate-fuzzy">
*[[Media:Importvorlage_Lieferanten_(1).xlsx|Template: Importvorlage Lieferanten.xlsx]]
</div>


== Import knowledge base (KB) elements ==

The importer allows you to import measures, controls, topics, audit questions, justification templates, or risks into an existing knowledge database. To do this, select the “Knowledge base” type in the importer. Next, you must specify the knowledge base into which the measures, controls, audit questions, topics, and justification templates should be imported. This must be a knowledge base that is still editable—that is, one that has not yet been published.

In order to import measures, controls, topics, review questions, and/or justification templates, the fields
* Title
* Record ID ''(unique identifier)''
must be assigned.

Caution: If the record ID already exists in the KB, no new record is created, but the old one is updated.

Furthermore, in all tabs there are the fields:
* Outline
* Description
* Status: ''(Date value)''

In the Question tab, there are also the fields:
* Question
* Type of question: This defines the type of the review question. Allowed values of the field are: "process question" or "technical question" or "information gathering". Process questions can be answered with a score from 1-5 according to the evaluation schema, technical questions with Yes/No/Partial, and information gatherings are answered by filling in the comment and/or uploading an attachment. If the column is not filled, all review questions will be imported as technical questions.
* linked topics ''(Record ID)''

In the Topic tab, there are also the fields:
* superordinate topic ''(Record ID)''
* linked review questions ''(Record ID)''

'''Note:''' For an import, columns from all tabs do not have to be assigned. So you can import topics, review questions, measures, controls, or justification templates separately.

'''Note:''' Topics and review questions that are then to be linked can be imported in the same Excel file. But you also have the option of importing linkages for topics/review questions that you have already imported or manually created before.

'''Note:''' Multiple record IDs separated by commas can be put into the fields linked review questions to topics and linked topics to review questions. This can be done with or without a space before/after the comma. Example: PF01, PF02, PF03.


=== Templates ===

*[[Medium:Importvorlage WDB Thema.xlsx|Template: Importvorlage WDB Thema.xslx]]
*[[Media:Importvorlage_WDB_Prüffrage.xlsx|Template: Importvorlage WDB Prüffrage.xslx]]
*[[Media:Importvorlage_WDB_Maßnahme.xlsx|Template: Importvorlage WDB Maßnahme.xslx]]
*[[Media:Importvorlage_WDB_Kontrolle.xlsx|Template: Importvorlage WDB Kontrolle.xslx]]
*[[Medium:Importvorlage WDB T-PF-M-K.xlsx|Template: Importvorlage WDB Thema, Prüffrage, Maßnahme und Kontrolle.xslx]]
*[[Medium:Importvorlage WDB Risiko.xlsx|Template: Importvorlage WDB Risiko.xslx]]


== User management ==

To import users, the "User" type must be selected during import.

There are two options:
* Create new user
* Update existing users

Users can be imported with the importer. When importing organizational units, data categories and resources, a responsible person can optionally be specified, which is then assigned or created and assigned.

If only the user name is specified in the course of the import of a structural element, the responsible person is assigned, but not modified. Therefore, the user must already exist. In the "Responsible" tab, all fields except for the user name can be ignored in this case.

===Create a new user with the importer===
When importing a file, HITGuard uses the data set ID in the import file to check whether it already exists anywhere in the HITGuard instance (system-wide) or not. If it does not exist, it is created again.

To create a new user, the following mandatory fields
*Username ''(system-wide unique identifier)
* E-mail address
* Password
* First name
*Last name
must be available and filled in. Only if this is the case, the import is possible.


=== Creation of a new user in the course of another import ===

If a responsible person is entered during import that has not yet been created in HITGuard, there are two variants of how HITGuard handles this:
# Active Directory Integration is disabled:
#:
#: The user is created completely new, so that this can be performed, the mandatory fields of the responsible person must be present and entered in the import file. These are:
#::* Username
#::* E-mail
#::* Password (between 12 and 20 characters, with at least 3 of the 4 criteria special characters, upper case, lower case and digits)
#: [[Datei:Verantwortlichen import 1.png|left|thumb|900px|mandatory fields when creating a new user]] 
# Active Directory integration is enabled:
#:
#: If Active Directory Integration is enabled, only users that exist in Active Directory can be created. However, the first name, last name and email fields can still be assigned. This means that it is possible to change the user's data during import and thus add or correct any errors or information from the Active Directory that is not maintained in HITGuard.


=== Update users ===

It is possible to update users with the help of the importer. This is useful, for example, if the e-mail or last name of a user changes. The importer checks at each import, if a user is entered, if additional fields like e-mail, last name, etc. exist in the import file, if yes, the content of these fields will be updated with the new content.

This makes it possible to keep information in HITGuard about users that do not exist or are not maintained in the Active Directory. It should be noted that HITGuard does not update the Active Directory!

'''Caution:''' The AD integration must be deactivated for the update of users with their own data import.


==== Deactivated users ====

If a deactivated user is entered or updated as the responsible person during an update, this user is not activated as a result, i.e. he does not change status. However, he will be updated and entered as the responsible person.

=== Template ===
*[[Medium:Importvorlage Benutzer.xlsx|Template: Importvorlage Benutzer.xlsx]]


== Structure of an import file ==

The importer supports two format types:
* CSV
* Excel files

=== Excel ===

The structure of an Excel file consists of a table in which all relevant data is represented as a column in a table. Each row corresponds, e.g., to a new organizational unit or other structure to be imported. During import, depending on the structure, the first row can or must be skipped if this row is the column header.

[[Datei:Excel org import example.PNG|left|thumb|900px|Example of an Excel import]]
 

=== CSV ===

The structure of a CSV file usually consists of one line, in which the column headings are separated by semicolons. Each additional line contains information about the structure to be imported. It is important that each line has the same number of columns (i.e. the same number of semicolons). Depending on the structure, the first line can or must be skipped during the import if this line contains the column headings.

[[Datei:Csv org import example.PNG|left|thumb|701px|Example of CSV import]]
 

=== HTML-formatting in the import ===
A few fields you can import as an Excel or CSV are HTML-fields in the application, meaning you can format them. You have the option of already adding this formatting in the import by using html-codes. This applies to, for example, the question section of review questions in knowledge bases, or the description fields of measures or risks.A few formatting examples:

{| class="wikitable"
!HTML-code
!Output
|-
|<pre><ul><li>Item 1</li><li>Item 2</li></ul></pre>
|<ul><li>Creates a</li><li>bullet list.</li></ul> Important: In a list of this kind you must not use line breaks in the Excel/CSV, as this will lead to empty lines in the result.
|-
|<pre>Line 1 Line 2</pre>
|Adds a simple line break.
|-
|<pre>bold</pre>
|Formats the text as bold.
|-
|<pre>italic</pre>
|Formats the text as italic.
|-
|<pre>unterlined</pre>
|Formats the text as unterlined.
|-
|<pre><s>struck through</s></pre>
|Formats the text as <s>struck through</s>.
|-
|}

You can also use an online HTML editor, format your text there, and then copy the result, meaning the code, into the Excel or CSV. Remember to remove any line breaks here.

2026-04-02T09:29:03Z

Faha: Faha lud eine neue Version von Datei:Importvorlage Risiko.xlsx hoch

== Versions ==
There are currently 2 versions of the API: "v1" and "v2". In Swagger you can switch back and forth between the two versions.
[[Datei:Swagger version wechseln.png|ohne|mini|Changing Version in Swagger]]
Currently the endpoints are distributed between the two versions and one should use both versions.

Datenimport/-export Schnittstelle

2026-03-19T12:50:00Z

Faha: Diese Seite wurde zum Übersetzen freigegeben

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.


'''Wichtig''': ID Parameter, die in der Dokumentation erwähnt werden, beziehen sich im Kontext der REST API nicht auf HITGuard interne IDs, sondern auf die in HITGuard hinterlegte "ID in Drittsystem".


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]] 


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien. DELETE /api/v2/asset-edges → Löscht manuell gesetzte Beziehungen in der Strukturanalyse zwischen Ressourcen und Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/v2/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. POST /api/v2/risks/submit → Erstellt ein Risiko im Status "Eingereicht" im angegebenen Managementsystem. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/v2/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
!Benutzer
|PUT /api/v2/users → Erstellt oder aktualisiert einen oder mehrere Benutzer. Achtung: Die Aktualisierung funktioniert nur, wenn die AD Integration deaktiviert ist.
|}


== Versionierung ==
Aktuell gibt es 2 Versionen der API: "v1" und "v2". In Swagger kann zwischen den Versionen hin und her gewechselt werden.
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zur Zeit sind die Endpunkte auf diese beiden Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.


Endpunkte, die in "v1" als veraltet ("'''Deprecated"''') markiert sind, sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog === 

==== Änderungen "v1" auf "v2" ==== 


* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt PUT /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne IDs angewiesen ist
*** Der "ID" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne ID
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert, da dies eine interne ID verwendet hat → nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.
** PUT /api/v2/risks ersetzt PUT /api/risks
*** Das Datenmodell wurde angepasst. Die "managementSystemId" wird nicht mehr auf oberer Ebene vergeben sondern je Risiko. Das Modell ist jetzt "RiskCreateOrUpdateDtoV2" und nicht mehr "HazardSituationImportDto"
*** Es kann jetzt auch der Status des Risiko über die API aktualisiert werden. Erlaubte werte sind: Active, Inactive, Accepted, Rejected
** POST /api/v2/risks/submit neuer Endpunkt zum importieren von Risiken im Status "Eingereicht"
** DELETE /api/v2/risks/{id} ersetzt DELETE /api/risks/{id}
** alle Endpunkte wurden in "v1" als veraltet markiert


Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datenimport/-export Schnittstelle

2026-03-19T12:49:07Z

Faha:

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.


'''Wichtig''': ID Parameter, die in der Dokumentation erwähnt werden, beziehen sich im Kontext der REST API nicht auf HITGuard interne IDs, sondern auf die in HITGuard hinterlegte "ID in Drittsystem".


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]] 


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien. DELETE /api/v2/asset-edges → Löscht manuell gesetzte Beziehungen in der Strukturanalyse zwischen Ressourcen und Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/v2/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. POST /api/v2/risks/submit → Erstellt ein Risiko im Status "Eingereicht" im angegebenen Managementsystem. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/v2/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
!Benutzer
|PUT /api/v2/users → Erstellt oder aktualisiert einen oder mehrere Benutzer. Achtung: Die Aktualisierung funktioniert nur, wenn die AD Integration deaktiviert ist.
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API: "v1" und "v2". In Swagger kann zwischen den Versionen hin und her gewechselt werden.
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zur Zeit sind die Endpunkte auf diese beiden Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.


Endpunkte, die in "v1" als veraltet ("'''Deprecated"''') markiert sind, sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog === 

==== Änderungen "v1" auf "v2" ==== 


* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt PUT /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne IDs angewiesen ist
*** Der "ID" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne ID
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert, da dies eine interne ID verwendet hat → nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.
** PUT /api/v2/risks ersetzt PUT /api/risks
*** Das Datenmodell wurde angepasst. Die "managementSystemId" wird nicht mehr auf oberer Ebene vergeben sondern je Risiko. Das Modell ist jetzt "RiskCreateOrUpdateDtoV2" und nicht mehr "HazardSituationImportDto"
*** Es kann jetzt auch der Status des Risiko über die API aktualisiert werden. Erlaubte werte sind: Active, Inactive, Accepted, Rejected
** POST /api/v2/risks/submit neuer Endpunkt zum importieren von Risiken im Status "Eingereicht"
** DELETE /api/v2/risks/{id} ersetzt DELETE /api/risks/{id}
** alle Endpunkte wurden in "v1" als veraltet markiert


Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datenimport/-export Schnittstelle

2026-03-19T12:39:42Z

Faha: /* Swagger/OpenAPI Dokumentation */

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.


'''Wichtig''': ID Parameter, die in der Dokumentation erwähnt werden, beziehen sich im Kontext der REST API nicht auf HITGuard interne IDs, sondern auf die in HITGuard hinterlegte "ID in Drittsystem".


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]] 


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien. DELETE /api/v2/asset-edges → Löscht manuell gesetzte Beziehungen in der Strukturanalyse zwischen Ressourcen und Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/v2/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses.
POST /api/v2/risks/submit → Erstellt ein Risiko im Status "Eingereicht" im angegebenen Managementsystem. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/v2/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
!Benutzer
|PUT /api/v2/users → Erstellt oder aktualisiert einen oder mehrere Benutzer. Achtung: Die Aktualisierung funktioniert nur, wenn die AD Integration deaktiviert ist.
|}


== Versionierung ==
Aktuell gibt es 2 Versionen der API: "v1" und "v2". In Swagger kann zwischen den Versionen hin und her gewechselt werden.
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zur Zeit sind die Endpunkte auf diese beiden Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.


Endpunkte, die in "v1" als veraltet ("'''Deprecated"''') markiert sind, sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog === 

==== Änderungen "v1" auf "v2" ==== 


* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt PUT /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne IDs angewiesen ist
*** Der "ID" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne ID
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert, da dies eine interne ID verwendet hat → nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.
** PUT /api/v2/risks ersetzt PUT /api/risks
*** Das Datenmodell wurde angepasst. Die "managementSystemId" wird nicht mehr auf oberer Ebene vergeben sondern je Risiko. Das Modell ist jetzt "RiskCreateOrUpdateDtoV2" und nicht mehr "HazardSituationImportDto"
*** Es kann jetzt auch der Status des Risiko über die API aktualisiert werden. Erlaubte werte sind: Active, Inactive, Accepted, Rejected
** POST /api/v2/risks/submit neuer Endpunkt zum importieren von Risiken im Status "Eingereicht"
** DELETE /api/v2/risks/{id} ersetzt DELETE /api/risks/{id}
** alle Endpunkte wurden in "v1" als veraltet markiert


Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datenimport/-export Schnittstelle

2025-10-28T13:35:02Z

Faha: /* Swagger/OpenAPI Dokumentation */

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.

'''Wichtig''': Id Parameter die in der Dokumentation erwähnt werden beziehen sich im Kontext der REST API nicht auf HITGuard interne Ids, sondern auf die in HITGuard hinterlegte "ID in Drittsystem".


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]]


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API "v1" und "v2". Im Swagger kann zwischen den Versionen hin und her gewechselt werden .
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zurzeit sind die Endpunkte auf diese 2 Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.

Endpunkte die in "v1" als veraltet ("'''Deprecated"''') markiert sind sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog ===

==== Änderungen "v1" auf "v2" ====

* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt PUT /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne Ids angewiesen ist
*** Der "Id" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne Id
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert da dies eine interne Id verwendet hat => nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.

Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datenimport/-export Schnittstelle

2025-10-28T13:27:42Z

Faha: /* Änderungen "v1" auf "v2" */

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]]


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API "v1" und "v2". Im Swagger kann zwischen den Versionen hin und her gewechselt werden .
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zurzeit sind die Endpunkte auf diese 2 Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.

Endpunkte die in "v1" als veraltet ("'''Deprecated"''') markiert sind sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog ===

==== Änderungen "v1" auf "v2" ====

* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt PUT /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne Ids angewiesen ist
*** Der "Id" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne Id
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert da dies eine interne Id verwendet hat => nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.

Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datenimport/-export Schnittstelle

2025-10-28T13:27:30Z

Faha: /* Änderungen "v1" auf "v2" */

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]]


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API "v1" und "v2". Im Swagger kann zwischen den Versionen hin und her gewechselt werden .
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zurzeit sind die Endpunkte auf diese 2 Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.

Endpunkte die in "v1" als veraltet ("'''Deprecated"''') markiert sind sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog ===

==== Änderungen "v1" auf "v2" ====

* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne Ids angewiesen ist
*** Der "Id" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne Id
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert da dies eine interne Id verwendet hat => nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.

Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datenimport/-export Schnittstelle

2025-10-28T13:25:46Z

Faha: /* Swagger/OpenAPI Dokumentation */

<translate>

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.


Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).


Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!


[[Datei:REST API Importprotokoll.png|thumb|left|900px]] 

== Konfiguration == 


Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:


* <code>"RestApi": { "Enabled": true } </code>


Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

== Einstellungen == 


Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.


[[Datei:REST API Einstellungen.png|thumb|left|902px]] 


* REST Schnittstelle aktivieren:
:: Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.


* SwaggerUI aktivieren:
:: Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.
::Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.
:: Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.
:: Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

== Swagger/OpenAPI Dokumentation == 


Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.


Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.


Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.


[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]]


{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
|-
!Meldungen
|PUT /api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
|-
!Managementsysteme
|GET /api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
|-
!Benutzer
|DELETE /api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
|-
!Datenkategorien
|PUT /api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET /api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET /api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE /api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
|-
!Maßnahmen
|PUT /api/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. PUT /api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT /api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE /api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET /api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
|-
!Organisationseinheiten
|PUT /api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET /api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE /api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
|-
!Prozesse
|PUT /api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET /api/processes → Erzeugt eine Liste der Prozesse. DELETE /api/processes/{id} → Löscht einen Prozess anhand der ID.
|-
!Ressourcen
|PUT /api/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API "v1" und "v2". Im Swagger kann zwischen den Versionen hin und her gewechselt werden .
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zurzeit sind die Endpunkte auf diese 2 Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.

Endpunkte die in "v1" als veraltet ("'''Deprecated"''') markiert sind sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog ===

==== Änderungen "v1" auf "v2" ====

* Maßnahmen (Measures)
** PUT /api/v2/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne Ids angewiesen ist
*** Der "Id" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne Id
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert da dies eine interne Id verwendet hat => nur noch PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.

Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== ApiKeys == 


Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!


Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.


ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.


[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]] 


ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.


[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]] 


Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.


[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]] 


Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.


[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]] 


Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.

</translate>

Datei:Swagger version wechseln.png

2025-10-28T12:39:42Z

Faha:

Login Möglichkeiten/en

2025-05-27T09:43:02Z

Faha:

HITGuard supports the Authentication Provider Active Directory (AD), Azure Active Directory (AAD), Active Directory Federation Services (ADFS) and OpenIdProvider.


== Active Driectory ==

The Active Directory is the only Authentication Provider that can be set at runtime of HITGuard. It can be configured by administrators and experts in the Global Settings.

More about Active Directory configuration can be found at [[Special:MyLanguage/Globale_Einstellungen#ldap| "Administration → Global Settings → LDAP"]].

== Azure Active Directory ==

To configure the Authentication Provider AAD or ADFS, the "appsettings.production.json" file of HITGuard must be modified. This file is located in the root directory of the installation folder.

In the ''AzureAd'' section, the following entries need to be customized to your Azure app:
*"Activated": true,
*"Instance": "https://login.microsoftonline.com/",
*"HITGuardBaseUrl": "https address where your HITGuard instance is accessible",
*"ClientId": "your-clientId-guid",
*"TenantId": "your-tententId-guid",
*"ClientSecret": "your-tententId-guid",

=== Single Sign On (SSO) ===

If the AAD is now set up as the Authentication Provider for HITGuard, users can log in to HITGuard via Single Sign On (see figure below).

The prerequisite is that a user exists in HITGuard whose e-mail address matches the e-mail address used to log in to AAD. This is because: When logging in via AAD for the first time, this is used to connect the AAD user with the HITGuard user. Subsequently, the e-mail address of the HITGuard user can be changed if necessary.

[[Datei:Login mit Azure Active Directory.PNG|left|thumb|800px|Login configured with Azure Active Directory]]
 

== Active Directory Federation Services ==

To configure an ADFS you have to proceed similar to the Azure Active Directory and add in the "appsettings.production.json" file the entries
*"MetadataAddress": "https://adfs.yourcompany.com/FederationMetadata/2007-06/FederationMetadata.xml",
*"Wtrealm": "https://www.hitguard.com/"
configure.

=== Single Sign On (SSO) ===

Siehe Azure Active Directory (AAD) SSO.

== OpenID Connect Provider ==

To set up an OpenID Connect provider, changes must be made in the "appsettings.production.json" file. OpenID Connect offers many flexible settings that can be customised depending on the provider.

=== Steps for configuration ===
# Add the configuration in the "appsettings.production.json" file.
# Make sure to use the correct "ClientId", "ClientSecret" and "Authority" for each provider. This information is different for each OpenID Connect provider and must be configured according to the respective providers. In addition, a corresponding unique "CallbackPath" must be defined for each provider, as well as a "Name" that is used for the login button.
# Set the setting "OpenIdConnect.Enabled" to "true" so that the providers can actually be used.
# '''Important''' Restart the application after changing the configuration by doing this via the IIS Manager (ideally with "stop" and "start", as "restart" sometimes does not restart the application completely).

If you have any further questions about configuring an OpenID Connect provider, please contact "office@togethersecure.com".


=== Example configuration ===

The following example shows how you can configure Google and Microsoft (without Active Directory) as OpenID Connect providers.

The Microsoft integration also shows how to use a custom claim so that existing users can log in directly with their Microsoft account without linking the account to their profile (see [[Special:MyLanguage/Profil|Profile]]).

<syntaxhighlight lang="json">
"AllowOpenIdConnectUserMappingByUsername": true, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's username when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a username, see "HitGuardUserNameClaim" to configure which claim provides the username)
"AllowOpenIdConnectUserMappingByEmail": false, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's email when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a matching email)
"OpenIdConnect": {
// If you need to authorize redirect URIs at the Provider, authorize '{HITGuard-domain}/Account/ExternalLoginCallback'
"Enabled": true,
"Providers": [
{
"Name": "Google", // This name will be displayed to the Users and needs to be unique. Entering 'Google' would for example display as Login with Google
"Authority": "https://accounts.google.com", // needs to point to the domain where the provider hosts the '/.well-known/openid-configuration', for google this would be e.g. 'https://accounts.google.com'"
"ClientId": "[Google-Client-Id]", // ClientId for your Application with the Provider
"ClientSecret": "[Google-Client-Secret]", // ClientSecret for your Application with the Provider
"CallbackPath": "/signin-oidc-google", // CallbackPath registered with the Provider, must be unique from other providers. Choose any valid path e.g.: '/signin-oidc-google
},
{
"Name": "Microsoft",
"Authority": "https://login.microsoftonline.com/[Microsoft-Tenatn-Id]/v2.0",
"ClientId": "[Microsoft-Client-Id]",
"ClientSecret": "[Microsoft-Client-Secret]",
"CallbackPath": "/signin-oidc-microsoft",
"GetClaimsFromUserInfoEndpoint": true, // If set to true additional claims will be retrieved from the UserInfo endpoint, by default this is false so it will only look at claims in the ID_token, set this to true, if you configure a different "HitGuardUserNameClaim" and do not include it in the ID_token
"HitGuardUserNameClaim": "hitguard_username", // If AllowOpenIdConnectUserMappingByUsername (toplevel) is set, this property can be used to customize which claim will have the hitgurad username that should be matched. The default of this is the "preferred_username" claim which should be present in the "profile" scope. If this is set to a different value, the Identity Provider needs to be configured to actually include the configured claim in the ID_token (or UserInfo endpoint, which requires "GetClaimsFromUserInfoEndpoint": true) returned to HITGuard.
}
]
}
</syntaxhighlight>

=== Notes ===
* The `ClientId` and `ClientSecret` must be created individually for each OpenID Connect provider account. You can obtain these directly from Google or Microsoft when you register an application in the respective developer portal.
* Make sure that the callback URL is configured correctly. This URL is used during the authentication process to receive the response from the provider.
* If you want to use a custom claim to map to username, you must ensure that the OpenID Connect provider returns this claim via the ID token or the UserInfo endpoint and configure it accordingly in "appsetting.production.json".

Translations:Login Möglichkeiten/25/en

2025-05-27T09:42:55Z

Faha:

<syntaxhighlight lang="json">
"AllowOpenIdConnectUserMappingByUsername": true, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's username when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a username, see "HitGuardUserNameClaim" to configure which claim provides the username)
"AllowOpenIdConnectUserMappingByEmail": false, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's email when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a matching email)
"OpenIdConnect": {
// If you need to authorize redirect URIs at the Provider, authorize '{HITGuard-domain}/Account/ExternalLoginCallback'
"Enabled": true,
"Providers": [
{
"Name": "Google", // This name will be displayed to the Users and needs to be unique. Entering 'Google' would for example display as Login with Google
"Authority": "https://accounts.google.com", // needs to point to the domain where the provider hosts the '/.well-known/openid-configuration', for google this would be e.g. 'https://accounts.google.com'"
"ClientId": "[Google-Client-Id]", // ClientId for your Application with the Provider
"ClientSecret": "[Google-Client-Secret]", // ClientSecret for your Application with the Provider
"CallbackPath": "/signin-oidc-google", // CallbackPath registered with the Provider, must be unique from other providers. Choose any valid path e.g.: '/signin-oidc-google
},
{
"Name": "Microsoft",
"Authority": "https://login.microsoftonline.com/[Microsoft-Tenatn-Id]/v2.0",
"ClientId": "[Microsoft-Client-Id]",
"ClientSecret": "[Microsoft-Client-Secret]",
"CallbackPath": "/signin-oidc-microsoft",
"GetClaimsFromUserInfoEndpoint": true, // If set to true additional claims will be retrieved from the UserInfo endpoint, by default this is false so it will only look at claims in the ID_token, set this to true, if you configure a different "HitGuardUserNameClaim" and do not include it in the ID_token
"HitGuardUserNameClaim": "hitguard_username", // If AllowOpenIdConnectUserMappingByUsername (toplevel) is set, this property can be used to customize which claim will have the hitgurad username that should be matched. The default of this is the "preferred_username" claim which should be present in the "profile" scope. If this is set to a different value, the Identity Provider needs to be configured to actually include the configured claim in the ID_token (or UserInfo endpoint, which requires "GetClaimsFromUserInfoEndpoint": true) returned to HITGuard.
}
]
}
</syntaxhighlight>

Login Möglichkeiten

2025-05-27T09:42:06Z

Faha:

<translate>

HITGuard unterstützt die Authentication Provider Active Directory (AD), Azure Active Directory (AAD), Active Directory Federation Services (ADFS) und OpenIdProvider.

== Active Directory == 


Das Active Directory ist der einzige Authentication Provider, der zur Laufzeit von HITGuard eingestellt werden kann. Es kann von Administratoren und Experten in den Globalen Einstellungen konfiguriert werden.


Mehr über die Active Directory Konfiguration ist unter [[Special:MyLanguage/Globale_Einstellungen#ldap| "Administration → Globale Einstellungen → LDAP"]] zu finden.

== Azure Active Directory == 


Um die Authentication Provider AAD oder ADFS zu konfigurieren, muss die Datei "appsettings.production.json" von HITGuard geändert werden. Diese Datei befindet sich im Wurzelverzeichnis des Installationsordners.


In der Sektion ''AzureAd'' müssen folgende Einträge an Ihre Azure-App angepasst werden:
*"Activated": true,
*"Instance": "https://login.microsoftonline.com/",
*"HITGuardBaseUrl": "https-Adresse unter der Ihre HITGuard-Instanz erreichbar ist",
*"ClientId": "your-clientId-guid",
*"TenantId": "your-tententId-guid",
*"ClientSecret": "your-tententId-guid",

=== Single Sign On (SSO) === 


Ist das AAD nun als Authentication Provider für HITGuard eingerichtet, können sich Benutzer per Single Sign On bei HITGuard anmelden (siehe Abbildung unten).


Voraussetzung ist, dass ein Benutzer in HITGuard existiert, dessen E-Mail-Adresse mit der E-Mail-Adresse, die zur Anmeldung im AAD verwendet wird, übereinstimmt. Denn: Bei der ersten Anmeldung via AAD wird diese verwendet um den AAD-Benutzer mit dem HITGuard-Benutzer zu verbinden. Anschließend kann die E-Mail-Adresse des HITGuard-Benutzers bei Bedarf geändert werden.


[[Datei:Login mit Azure Active Directory.PNG|left|thumb|800px|Login mit Azure Active Directory konfiguriert]]
 

== Active Directory Federation Services == 


Um ein ADFS zu konfigurieren müssen sie ähnlich wie beim Azure Active Directory vorgehen und im "appsettings.production.json" File die Einträge
*"MetadataAddress": "https://adfs.yourcompany.com/FederationMetadata/2007-06/FederationMetadata.xml",
*"Wtrealm": "https://www.hitguard.com/"
konfigurieren.

=== Single Sign On (SSO) === 


Siehe Azure Active Directory (AAD) SSO.

== OpenID Connect Provider == 


Um einen OpenID Connect Provider einzurichten, müssen in der Datei "appsettings.production.json" Änderungen vorgenommen werden. OpenID Connect bietet viele flexible Einstellungen, die je nach Provider angepasst werden können.


=== Schritte zur Konfiguration ===
# Fügen Sie die Konfiguration in der Datei "appsettings.production.json" hinzu.
# Achten Sie darauf, die korrekte "ClientId", "ClientSecret" und "Authority" für jeden Provider zu verwenden. Diese Informationen sind bei jedem OpenID Connect-Provider unterschiedlich und müssen entsprechend den jeweiligen Anbietern konfiguriert werden. Außerdem muss für jeden Provider ein entsprechender einzigartiger "CallbackPath" definiert werden, sowie ein "Name" der für den Login Button verwendet wird.
# Setzen Sie die Einstellung `"OpenIdConnect.Enabled"` auf `true`, damit die Provider auch wirklich verwendet werden können.
# '''Wichtig''' Starten Sie die Anwendung nach der Änderung der Konfiguration neu, indem Sie dies über den IIS Manager tun (idealerweise mit "stop" und "start", da "restart" manchmal die Anwendung nicht vollständig neu startet).


Bei weiteren Fragen zur Konfiguration eines OpenID Connect Providers melden Sie sich unter "office@togethersecure.com".

=== Beispiel-Konfiguration === 


Im folgenden Beispiel sehen Sie, wie Sie Google und Microsoft (ohne Active Directory) als OpenID Connect Provider konfigurieren können.


Die Microsoft-Integration zeigt außerdem, wie ein "custom claim" verwendet wird, damit sich bestehende Benutzer direkt mit ihrem Microsoft-Konto anmelden können, ohne das Konto mit ihrem Profil zu verknüpfen (siehe [[Special:MyLanguage/Profil|Profil]]).


<syntaxhighlight lang="json">
"AllowOpenIdConnectUserMappingByUsername": true, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's username when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a username, see "HitGuardUserNameClaim" to configure which claim provides the username)
"AllowOpenIdConnectUserMappingByEmail": false, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's email when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a matching email)
"OpenIdConnect": {
// If you need to authorize redirect URIs at the Provider, authorize '{HITGuard-domain}/Account/ExternalLoginCallback'
"Enabled": true,
"Providers": [
{
"Name": "Google", // This name will be displayed to the Users and needs to be unique. Entering 'Google' would for example display as Login with Google
"Authority": "https://accounts.google.com", // needs to point to the domain where the provider hosts the '/.well-known/openid-configuration', for google this would be e.g. 'https://accounts.google.com'"
"ClientId": "[Google-Client-Id]", // ClientId for your Application with the Provider
"ClientSecret": "[Google-Client-Secret]", // ClientSecret for your Application with the Provider
"CallbackPath": "/signin-oidc-google", // CallbackPath registered with the Provider, must be unique from other providers. Choose any valid path e.g.: '/signin-oidc-google
},
{
"Name": "Microsoft",
"Authority": "https://login.microsoftonline.com/[Microsoft-Tenatn-Id]/v2.0",
"ClientId": "[Microsoft-Client-Id]",
"ClientSecret": "[Microsoft-Client-Secret]",
"CallbackPath": "/signin-oidc-microsoft",
"GetClaimsFromUserInfoEndpoint": true, // If set to true additional claims will be retrieved from the UserInfo endpoint, by default this is false so it will only look at claims in the ID_token, set this to true, if you configure a different "HitGuardUserNameClaim" and do not include it in the ID_token
"HitGuardUserNameClaim": "hitguard_username", // If AllowOpenIdConnectUserMappingByUsername (toplevel) is set, this property can be used to customize which claim will have the hitgurad username that should be matched. The default of this is the "preferred_username" claim which should be present in the "profile" scope. If this is set to a different value, the Identity Provider needs to be configured to actually include the configured claim in the ID_token (or UserInfo endpoint, which requires "GetClaimsFromUserInfoEndpoint": true) returned to HITGuard.
}
]
}
</syntaxhighlight>


=== Hinweise ===
* Die `ClientId` und `ClientSecret` müssen für jedes OpenID Connect-Provider-Konto individuell erstellt werden. Diese erhalten Sie direkt von Google oder Microsoft, wenn Sie eine Anwendung im jeweiligen Developer-Portal registrieren.
* Achten Sie darauf, dass die Callback-URL korrekt konfiguriert ist. Diese URL wird beim Authentifizierungsprozess verwendet, um die Antwort vom Provider zu empfangen.
* Wenn Sie einen benutzerdefinierten Claim zum Mappen auf Benutzername verwenden wollen, müssen Sie sicherstellen, dass der OpenID Connect Provider diesen Claim über den ID-Token oder den UserInfo-Endpunkt zurückgibt und im "appsetting.production.json" entsprechend konfigurieren.

</translate>

Login Möglichkeiten/en

2025-04-11T11:04:33Z

Faha: Die Seite wurde neu angelegt: „=== Example configuration ===“

HITGuard supports the Authentication Provider Active Directory (AD), Azure Active Directory (AAD), Active Directory Federation Services (ADFS) and OpenIdProvider.


== Active Driectory ==

The Active Directory is the only Authentication Provider that can be set at runtime of HITGuard. It can be configured by administrators and experts in the Global Settings.

More about Active Directory configuration can be found at [[Special:MyLanguage/Globale_Einstellungen#ldap| "Administration → Global Settings → LDAP"]].

== Azure Active Directory ==

To configure the Authentication Provider AAD or ADFS, the "appsettings.production.json" file of HITGuard must be modified. This file is located in the root directory of the installation folder.

In the ''AzureAd'' section, the following entries need to be customized to your Azure app:
*"Activated": true,
*"Instance": "https://login.microsoftonline.com/",
*"HITGuardBaseUrl": "https address where your HITGuard instance is accessible",
*"ClientId": "your-clientId-guid",
*"TenantId": "your-tententId-guid",
*"ClientSecret": "your-tententId-guid",

=== Single Sign On (SSO) ===

If the AAD is now set up as the Authentication Provider for HITGuard, users can log in to HITGuard via Single Sign On (see figure below).

The prerequisite is that a user exists in HITGuard whose e-mail address matches the e-mail address used to log in to AAD. This is because: When logging in via AAD for the first time, this is used to connect the AAD user with the HITGuard user. Subsequently, the e-mail address of the HITGuard user can be changed if necessary.

[[Datei:Login mit Azure Active Directory.PNG|left|thumb|800px|Login configured with Azure Active Directory]]
 

== Active Directory Federation Services ==

To configure an ADFS you have to proceed similar to the Azure Active Directory and add in the "appsettings.production.json" file the entries
*"MetadataAddress": "https://adfs.yourcompany.com/FederationMetadata/2007-06/FederationMetadata.xml",
*"Wtrealm": "https://www.hitguard.com/"
configure.

=== Single Sign On (SSO) ===

Siehe Azure Active Directory (AAD) SSO.

== OpenID Connect Provider ==

To set up an OpenID Connect provider, changes must be made in the "appsettings.production.json" file. OpenID Connect offers many flexible settings that can be customised depending on the provider.

=== Steps for configuration ===
# Add the configuration in the "appsettings.production.json" file.
# Make sure to use the correct "ClientId", "ClientSecret" and "Authority" for each provider. This information is different for each OpenID Connect provider and must be configured according to the respective providers. In addition, a corresponding unique "CallbackPath" must be defined for each provider, as well as a "Name" that is used for the login button.
# Set the setting "OpenIdConnect.Enabled" to "true" so that the providers can actually be used.
# '''Important''' Restart the application after changing the configuration by doing this via the IIS Manager (ideally with "stop" and "start", as "restart" sometimes does not restart the application completely).

If you have any further questions about configuring an OpenID Connect provider, please contact "office@togethersecure.com".


=== Example configuration ===

The following example shows how you can configure Google and Microsoft (without Active Directory) as OpenID Connect providers.

The Microsoft integration also shows how to use a custom claim so that existing users can log in directly with their Microsoft account without linking the account to their profile (see [[Special:MyLanguage/Profil|Profile]]).

<syntaxhighlight lang="json">
{
"AllowOpenIdConnectUserMappingByUsername": true, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's username when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a username, see "HitGuardUserNameClaim" to configure which claim provides the username)
"AllowOpenIdConnectUserMappingByEmail": false, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's email when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a matching email)
"OpenIdConnect": {
// If you need to authorize redirect URIs at the Provider, authorize '{HITGuard-domain}/Account/ExternalLoginCallback'
"Enabled": true,
"Providers": [
{
"Name": "Google", // This name will be displayed to the Users and needs to be unique. Entering 'Google' would for example display as Login with Google
"Authority": "https://accounts.google.com", // needs to point to the domain where the provider hosts the '/.well-known/openid-configuration', for google this would be e.g. 'https://accounts.google.com'"
"ClientId": "[Google-Client-Id]", // ClientId for your Application with the Provider
"ClientSecret": "[Google-Client-Secret]", // ClientSecret for your Application with the Provider
"CallbackPath": "/signin-oidc-google", // CallbackPath registered with the Provider, must be unique from other providers. Choose any valid path e.g.: '/signin-oidc-google
},
{
"Name": "Microsoft",
"Authority": "https://login.microsoftonline.com/[Microsoft-Tenatn-Id]/v2.0",
"ClientId": "[Microsoft-Client-Id]",
"ClientSecret": "[Microsoft-Client-Secret]",
"CallbackPath": "/signin-oidc-microsoft",
"GetClaimsFromUserInfoEndpoint": true, // If set to true additional claims will be retrieved from the UserInfo endpoint, by default this is false so it will only look at claims in the ID_token, set this to true, if you configure a different "HitGuardUserNameClaim" and do not include it in the ID_token
"HitGuardUserNameClaim": "hitguard_username", // If AllowOpenIdConnectUserMappingByUsername (toplevel) is set, this property can be used to customize which claim will have the hitgurad username that should be matched. The default of this is the "preferred_username" claim which should be present in the "profile" scope. If this is set to a different value, the Identity Provider needs to be configured to actually include the configured claim in the ID_token (or UserInfo endpoint, which requires "GetClaimsFromUserInfoEndpoint": true) returned to HITGuard.
}
]
}
}
</syntaxhighlight>

=== Notes ===
* The `ClientId` and `ClientSecret` must be created individually for each OpenID Connect provider account. You can obtain these directly from Google or Microsoft when you register an application in the respective developer portal.
* Make sure that the callback URL is configured correctly. This URL is used during the authentication process to receive the response from the provider.
* If you want to use a custom claim to map to username, you must ensure that the OpenID Connect provider returns this claim via the ID token or the UserInfo endpoint and configure it accordingly in "appsetting.production.json".

Translations:Login Möglichkeiten/26/en

2025-04-11T11:04:27Z

Faha: Die Seite wurde neu angelegt: „=== Notes === * The `ClientId` and `ClientSecret` must be created individually for each OpenID Connect provider account. You can obtain these directly from Google or Microsoft when you register an application in the respective developer portal. * Make sure that the callback URL is configured correctly. This URL is used during the authentication process to receive the response from the provider. * If you want to use a custom claim to map to username, you m…“

=== Notes ===
* The `ClientId` and `ClientSecret` must be created individually for each OpenID Connect provider account. You can obtain these directly from Google or Microsoft when you register an application in the respective developer portal.
* Make sure that the callback URL is configured correctly. This URL is used during the authentication process to receive the response from the provider.
* If you want to use a custom claim to map to username, you must ensure that the OpenID Connect provider returns this claim via the ID token or the UserInfo endpoint and configure it accordingly in "appsetting.production.json".

Translations:Login Möglichkeiten/25/en

2025-04-11T11:03:58Z

Faha: Die Seite wurde neu angelegt: „<syntaxhighlight lang="json"> { "AllowOpenIdConnectUserMappingByUsername": true, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's username when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a username, see "HitGuardUserNameClaim" to configure which claim provides the username) "AllowOpenIdConnect…“

<syntaxhighlight lang="json">
{
"AllowOpenIdConnectUserMappingByUsername": true, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's username when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a username, see "HitGuardUserNameClaim" to configure which claim provides the username)
"AllowOpenIdConnectUserMappingByEmail": false, // Allow mapping of OpenIdConnect (or Microsoft Entra ID) user with HITGuard user by OpenIdConnect username with HITGuard user's email when first logging in with OpenIdConnect if activated. (i.e. the OpenIdConnect account gets associated with a hitguard user that has a matching email)
"OpenIdConnect": {
// If you need to authorize redirect URIs at the Provider, authorize '{HITGuard-domain}/Account/ExternalLoginCallback'
"Enabled": true,
"Providers": [
{
"Name": "Google", // This name will be displayed to the Users and needs to be unique. Entering 'Google' would for example display as Login with Google
"Authority": "https://accounts.google.com", // needs to point to the domain where the provider hosts the '/.well-known/openid-configuration', for google this would be e.g. 'https://accounts.google.com'"
"ClientId": "[Google-Client-Id]", // ClientId for your Application with the Provider
"ClientSecret": "[Google-Client-Secret]", // ClientSecret for your Application with the Provider
"CallbackPath": "/signin-oidc-google", // CallbackPath registered with the Provider, must be unique from other providers. Choose any valid path e.g.: '/signin-oidc-google
},
{
"Name": "Microsoft",
"Authority": "https://login.microsoftonline.com/[Microsoft-Tenatn-Id]/v2.0",
"ClientId": "[Microsoft-Client-Id]",
"ClientSecret": "[Microsoft-Client-Secret]",
"CallbackPath": "/signin-oidc-microsoft",
"GetClaimsFromUserInfoEndpoint": true, // If set to true additional claims will be retrieved from the UserInfo endpoint, by default this is false so it will only look at claims in the ID_token, set this to true, if you configure a different "HitGuardUserNameClaim" and do not include it in the ID_token
"HitGuardUserNameClaim": "hitguard_username", // If AllowOpenIdConnectUserMappingByUsername (toplevel) is set, this property can be used to customize which claim will have the hitgurad username that should be matched. The default of this is the "preferred_username" claim which should be present in the "profile" scope. If this is set to a different value, the Identity Provider needs to be configured to actually include the configured claim in the ID_token (or UserInfo endpoint, which requires "GetClaimsFromUserInfoEndpoint": true) returned to HITGuard.
}
]
}
}
</syntaxhighlight>

Translations:Login Möglichkeiten/24/en

2025-04-11T11:03:51Z

Faha: Die Seite wurde neu angelegt: „The Microsoft integration also shows how to use a custom claim so that existing users can log in directly with their Microsoft account without linking the account to their profile (see Profile).“

The Microsoft integration also shows how to use a custom claim so that existing users can log in directly with their Microsoft account without linking the account to their profile (see [[Special:MyLanguage/Profil|Profile]]).

Translations:Login Möglichkeiten/23/en

2025-04-11T11:03:33Z

Faha: Die Seite wurde neu angelegt: „The following example shows how you can configure Google and Microsoft (without Active Directory) as OpenID Connect providers.“

The following example shows how you can configure Google and Microsoft (without Active Directory) as OpenID Connect providers.