Merge branch 'mr-environments' into 'main'

Add description of environments

See merge request !164

docs/changelog.md

@@ -2,7 +2,11 @@
 
 Das Format dieser Datei basiert auf [Keep a Changelog](https://keepachangelog.com/de).
 
-Das hier veröffentlichte Changelog bezieht sich auf die [Testinstanz von FIT-Connect](https://docs.fitko.de/fit-connect/docs/getting-started/first-steps#test-infrastruktur).
+Das hier veröffentlichte Changelog bezieht sich auf die [Testinstanz von FIT-Connect](https://docs.fitko.de/fit-connect/docs/getting-started/first-steps#testing).
+
+## 2022-04-27
+### Dokumentation
+- [Beschreibung der Betriebsumgebungen](getting-started/first-steps.mdx#environments) ergänzt
 
 ## 2022-05-03
 ### Dokumentation

docs/getting-started/authentication.mdx

@@ -12,7 +12,7 @@ Als Voraussetzungen hierfür ist es notwendig, Accounts für [API-Clients im Sel
 ## Abruf von Access Tokens beim OAuth-Dienst
 
 :::note Hinweis
-Die URL der Submission API und die OAuth-Token-URL finden sich im Artikel [Erste Schritte](first-steps.mdx#test-infrastruktur).
+Die URL der Submission API und die OAuth-Token-URL finden sich im Artikel [Erste Schritte](first-steps.mdx#testing).
 :::
 
 Fast alle Anfragen an die FIT-Connect Submission API müssen authentifiziert werden.
@@ -121,5 +121,5 @@ Authorization: Bearer ey...
 ```
 
 :::note Hinweis
-Die URL der Submission API findet sich im Artikel [Erste Schritte](first-steps.mdx#test-infrastruktur).
+Die URL der Submission API findet sich im Artikel [Erste Schritte](first-steps.mdx#testing).
 :::

docs/getting-started/first-steps.mdx

@@ -13,15 +13,28 @@ Kern von FIT-Connect ist der Zustelldienst, der sendende und empfangende Systeme
 Jedes empfangende System (Fachverfahren / virtuelle Poststelle) verfügt über einen oder mehrere Zustellpunkte (Destinations), an die Einreichungen (Anträge oder Berichte) gesendet werden.
 Zustellpunkte können von empfangenden Systemen [über das Self-Service-Portal](./account.mdx) konfiguriert und von sendenden Systemen adressiert werden.
 
-## Test-Infrastruktur
+:::tip Hinweis
+Auf den folgenden Seiten stellen wir Code-Beispiele für die Anbindung von IT-Systemen an FIT-Connect zur Verfügung. Die Code-Beispiele veranschaulichen und vereinfachen die konkrete Implementierung der Nutzung der Programmierschnittstellen (APIs) von FIT-Connect. Diese Schnittstellen basieren auf gängigen offenen Standards und ermöglichen auch über die bereitgestellten Code-Beispiel hinaus eine Anbindung an FIT-Connect mit allen gängigen Programmiersprachen.
+:::
+
+## Betriebsumgebungen der FIT-Connect-Infrastruktur {#environments}
+
+### Übersicht
+Für FIT-Connect stehen derzeit mehrere Betriebsumgebungen bereit, die jeweils einen etwas anderen Zweck erfüllen.
+Umgebungen, die von der FITKO zu Test- und Entwicklungszwecken bereitgestellt werden, stehen unter einer Subdomain unterhalb von `fitko.dev` zur Verfügung.
+Produktive und produktivnahe Umgebungen stehen unter einer Subdomain unterhalb von `fitko.net` (bzw. unterhalb von `niedersachsen.de` für die bei IT.Niedersachsen betriebenen Infrastrukturen) zur Verfügung.
+
+| Umgebung                           | Zweck und Zielgruppe |
+| ---------------------------------- | -------------------- |
+| Testumgebung (`testing`)           | **Zweck**: Die Testumgebung dient vorrangig Anbindungstests und der Erprobung neuer Features.<br/>**Zielgruppe**: Die Testumgebung steht allen Interessierten zur freien Nutzung zur Verfügung, darf nicht für produktive Zwecke genutzt werden und unterliegt keinerlei Verfügbarkeitsgarantien.<br/>**Besonderheiten**: In der Testumgebung können selbst-generierte Test-Zertifikate anstelle von Zertifikaten aus einer PKI-Infrastruktur genutzt werden. |
+| Staging-/Referenzumgebung (`refz`) | **Zweck**: Die Stagingumgebung, auch Referenzumgebung genannt, ist identisch zur Produktivumgebung konfiguriert und dient dem Test von Updates der an FIT-Connect angebundenen Systeme, bevor diese an die Produktivumgebung angebunden werden. Zudem dient die Stagingumgebung der Gewährleistung einer reibungslosen Funktionalität von Updates der FIT-Connect-Infrastruktur selbst, bevor diese auf der Produktivumgebung ausgerollt werden.<br/>**Zielgruppe**: Die Stagingumgebung steht ausschließlich Systemen zur Verfügung, die ebenfalls zum Zugriff auf die Produktivumgebung berechtigt sind.<br/>**Besonderheiten**: Die Nutzung der Stagingumgebung setzt den Einsatz von Zertifikaten aus der Verwaltungs-PKI voraus. |
+| Produktivumgebung (`prod`)         | **Zweck**: Die Produktivumgebung dient der produktiven Nutzung der FIT-Connect-Infrastruktur.<br/>**Zielgruppe**: Die Nutzung der Produktivumgebung ist Betreiber:innen vorbehalten, die entsprechende Nutzungsbedingungen unterzeichnet und einen Auftragsdatenverarbeitungsvertrag mit der FITKO abgeschlossen haben.<br/>**Besonderheiten**: Die Nutzung der Produktivumgebung setzt den Einsatz von Zertifikaten aus der Verwaltungs-PKI voraus. |
 
-Für Anbindungstests in der Testumgebung können Sie die folgenden Links & Infos verwenden:
+### Testumgebung {#testing}
+
+Für Anbindungstests in der Testumgebung können Sie die folgenden Endpunkte & Infos verwenden:
 
 - Self-Service-Portal der Testumgebung: siehe [Accountregistrierung und Client-Verwaltung](./account.mdx)
 - [OAuth Token URL](./authentication.mdx): `https://auth-testing.fit-connect.fitko.dev/token`
 - [Submission API](../apis/submission-api.mdx): `https://submission-api-testing.fit-connect.fitko.dev`
 - [Routing API](../apis/routing-api.mdx): `https://routing-api-testing.fit-connect.fitko.dev`
-
-:::tip Hinweis
-Auf den folgenden Seiten stellen wir Code-Beispiele für die Anbindung von IT-Systemen an FIT-Connect zur Verfügung. Die Code-Beispiele veranschaulichen und vereinfachen die konkrete Implementierung der Nutzung der Programmierschnittstellen (APIs) von FIT-Connect. Diese Schnittstellen basieren auf gängigen offenen Standards und ermöglichen auch über die bereitgestellten Code-Beispiel hinaus eine Anbindung an FIT-Connect mit allen gängigen Programmiersprachen.
-:::

docs/receiving/download-submission.mdx

@@ -8,7 +8,7 @@ import ApiLink from '@site/src/components/ApiLink'
 Der Abruf einer Einreichung ist über den Endpunkt <ApiLink api="submission-api" to="/v1/submissions/{submissionId}" /> möglich. Liegen zur Einreichung neben den verschlüsselten Metadaten (`encryptedMetadata`) und Fachdaten (`encryptedData`) zusätzlich weitere Anlagen vor, so sind die IDs der Anlagen im Feld `attachments` zu finden. Anlagen müssen separat heruntergeladen werden (siehe nächster Abschnitt). Einreichungen und deren Anlagen können dabei nur im Status Submitted oder Forwarded abgerufen werden.
 
 :::note Hinweis
-Die URL der Submission API findet sich im Artikel [Erste Schritte](../getting-started/first-steps.mdx#test-infrastruktur).
+Die URL der Submission API findet sich im Artikel [Erste Schritte](../getting-started/first-steps.mdx#testing).
 :::
 
 ```bash title="Abfrage der Einreichung inkl. Fachdaten und Metadaten"

docs/responsibilities/get-destination.mdx

@@ -15,7 +15,7 @@ Die über das Self-Service-Portal erstellten Zustellpunkte sind in der Testumgeb
 Dieses Feature ist als zukünftige Erweiterung geplant.
 Sofern eine Destination-ID bereits bekannt ist, können die in einem Zustellpunkt hinterlegten technischen Parameter übergangsweise auch über den Endpunkt <ApiLink api="submission-api" to="/v1/destinations/{destinationId}" /> der Submission API des zuständigen Zustelldienstes [abgerufen werden (siehe unten)](#submissionapi).
 
-Die [Konfiguration des Antragsroutings](routing.mdx) in der produktiven Umgebung ist bereits jetzt möglich. Entsprechend konfigurierte Zustellpunkte sind in der Produktivumgebung bereits über Routing API abrufbar. 
+Die [Konfiguration des Antragsroutings](routing.mdx) in der produktiven Umgebung ist bereits jetzt möglich. Entsprechend konfigurierte Zustellpunkte sind in der Produktivumgebung bereits über Routing API abrufbar.
 :::
 
 Die Ermittlung der `destinationId` und die Ermittlung der technischen Parameter über die Routing-API erfolgt über einen GET-Request auf den Endpunkt <ApiLink api="routing-api" to="/routes" /> des FIT-Connect Routingdienstes.
@@ -370,7 +370,7 @@ Dabei ist für das JSON des Payload zu beachten, dass
 
 #### Prüfung der vollständigen Signatur
 
-Um die Signatur zu überprüfen, ist es notwendig auf die verwendeten Schlüssel (im Format JSON Web Key, kurz JWK) zugreifen zu können. 
+Um die Signatur zu überprüfen, ist es notwendig auf die verwendeten Schlüssel (im Format JSON Web Key, kurz JWK) zugreifen zu können.
 Der Zustelldienst stellt ein JSON Web Key Set (JWKS) öffentlich zugänglich über den Endpunkt <ApiLink api="submission-api" to="/.well-known/jwks.json" /> bereit.
 Da der Zustelldienst mit mehreren Instanzen betrieben werden kann, kann es auch mehrere Endpunkte zum JWKS geben.
 Diese Endpunkte können dynamisch aus dem Payload (`Zustellpunkt`) erzeugt werden.
@@ -399,7 +399,7 @@ private final static String DVDV_SUBMISSIONURL_KEY = "submissionUrl";
 private final static String KEYSTORE_URL_ENDING = ".well-known/jwks.json";
 private final static String[] VALID_KEYSTORE_URLS = new String[]{ "https://submission-api-testing.fit-connect.fitko.dev/v1/.well-known/jwks.json"};
 
-protected void validateBySignedJWT(SignedJWT signedJWT) throws BadJOSEException, JOSEException, IOException, ParseException 
+protected void validateBySignedJWT(SignedJWT signedJWT) throws BadJOSEException, JOSEException, IOException, ParseException
   {
     //1. Prüfung auf erlaubten Algorithmus PS512
     if ( !JWSAlgorithm.PS512.equals(signedJWT.getHeader().getAlgorithm()) )
@@ -414,7 +414,7 @@ protected void validateBySignedJWT(SignedJWT signedJWT) throws BadJOSEException,
     Optional<URL> keyStoreUrl = getKeyStoreUrl(getBaseKeyStoreUrl(signedJWT));
     if ( keyStoreUrl.isEmpty() )
       throw new RuntimeException("No JWKSetUrl found in Payload!");
-    
+
     validateKeyStoreUrl(keyStoreUrl.get());
 
     //KeyStore laden
@@ -440,14 +440,14 @@ protected void validateBySignedJWT(SignedJWT signedJWT) throws BadJOSEException,
   }
 ```
 ```java
-  protected String getBaseKeyStoreUrl(SignedJWT signedJWT) 
+  protected String getBaseKeyStoreUrl(SignedJWT signedJWT)
   {
     Map<String, Object> payload = signedJWT.getPayload().toJSONObject();
     return String.valueOf(payload.get(DVDV_SUBMISSIONURL_KEY));
   }
 ```
 ```java
-  protected Optional<URL> getKeyStoreUrl(String baseKeyStoreUrl) 
+  protected Optional<URL> getKeyStoreUrl(String baseKeyStoreUrl)
   {
     if (baseKeyStoreUrl==null)
       throw new RuntimeException("KeyStoreUrl not set!");
@@ -455,18 +455,18 @@ protected void validateBySignedJWT(SignedJWT signedJWT) throws BadJOSEException,
       baseKeyStoreUrl+="/";
     baseKeyStoreUrl+= KEYSTORE_URL_ENDING;
 
-    try 
+    try
     {
       return Optional.of(new URL(baseKeyStoreUrl));
-    } 
-    catch (MalformedURLException e) 
+    }
+    catch (MalformedURLException e)
     {
-      throw new RuntimeException("KeyStoreUrl not valid! MalformedURLException for url " + baseKeyStoreUrl);			
+      throw new RuntimeException("KeyStoreUrl not valid! MalformedURLException for url " + baseKeyStoreUrl);
     }
   }
 ```
 ```java
-  public void validateKeyStoreUrl(URL url) 
+  public void validateKeyStoreUrl(URL url)
   {
     if ( !VALID_KEYSTORE_URLS.contains(String.valueOf(url)) )
       throw new RuntimeException("KeyStoreUrl not valid!");
@@ -561,7 +561,7 @@ Beispiel für die Response
 Zum Abruf der Zustellpunkt-Informationen stellt die Submission API einen Endpunkt bereit, der über Angabe des Parameters `destinationId` die technischen Parameter der Einreichung für den jeweiligen Zustellpunkt ausgibt. Diese kann genutzt werden, wenn die `destinationId` bereits bekannt ist. Die angebotenen Informationen über eine Destination unterscheiden sich fachlich nicht von den Information aus der Routing API. Bei der Submission API muss lediglich der Verschlüsselungsschlüssel über einen zusätzlichen Endpunkt abgerufen werden, anstatt diesen zusammen mit den anderen Informationen in einer Response zu erhalten (siehe Artikel [Verschlüsseln](../sending/encrypt.mdx)).
 
 :::note Hinweis
-Die URL der Submission API findet sich im Artikel [Erste Schritte](../getting-started/first-steps.mdx#test-infrastruktur).
+Die URL der Submission API findet sich im Artikel [Erste Schritte](../getting-started/first-steps.mdx#testing).
 :::
 
 <Tabs

docs/sending/start-submission.mdx

@@ -17,7 +17,7 @@ Die für das Anlegen von Einreichungen notwendige Struktur von Einreichungen und
 :::
 
 :::note Hinweis
-Die URL der Submission API findet sich im Artikel [Erste Schritte](../getting-started/first-steps.mdx#test-infrastruktur).
+Die URL der Submission API findet sich im Artikel [Erste Schritte](../getting-started/first-steps.mdx#testing).
 :::