Skip to content
Snippets Groups Projects
Commit e455ecc7 authored by Jan Zickermann's avatar Jan Zickermann
Browse files

#2 OZG-7121 pom: Remove outdated documentation and add helm to pipeline

parent 7aeea8d3
Branches
Tags
1 merge request!3Resolve "xta-test-server helm-chart mit Deployment und Keystore-Secrets/Certificate-Resources"
Pipeline #1285 skipped
Showing
with 21 additions and 937 deletions
// +++++++++++++++++++++++++++++++++++++++++++++++++++++++
// + Initial AsciiDoc editor configuration file - V1.0 +
// ++++++++++++++++++++++++++++++++++++++++++++++++++++++
//
// Did not found any configuration files, so create this at project root level.
// If you do not like those files to be generated - you can turn it off inside Asciidoctor Editor preferences.
//
// You can define editor specific parts here.
// For example: with next line you could set imagesdir attribute to subfolder "images" relative to the folder where this config file is located.
// :imagesdir: {asciidoctorconfigdir}/images
//
// For more information please take a look at https://github.com/de-jcup/eclipse-asciidoctor-editor/wiki/Asciidoctor-configfiles
......@@ -35,11 +35,21 @@ test:
script:
- mvn test $MAVEN_CLI_OPTS
test-helm:
stage: test
before_script:
- apk add --no-cache helm
script:
- helm template ./src/main/helm/ -f src/test/helm-linter-values.yaml
- helm lint -f src/test/helm-linter-values.yaml ./src/main/helm/
- cd src/main/helm && helm unittest -f '../../test/helm/**/*test.yaml' .
verify:
stage: test
script:
- mvn verify $MAVEN_CLI_OPTS
.get-version:
before_script:
- export PROJECT_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout $MAVEN_CLI_OPTS)
......@@ -67,6 +77,17 @@ push-merge-request-image-nexus:
- if: $CI_PIPELINE_SOURCE == 'merge_request_event'
when: manual
push-merge-request-helm-nexus:
stage: publish
extends: .get-version
before_script:
- apk add --no-cache helm
script:
- cd src/main/helm && helm package --version=MR-${CI_MERGE_REQUEST_IID}-${PROJECT_VERSION}
rules:
- if: $CI_PIPELINE_SOURCE == 'merge_request_event'
when: manual
# Snapshot jobs
push-snapshot-image-gitlab:
stage: publish
......
pipeline {
agent {
node {
label 'ozgcloud-jenkins-build-agent-jdk21'
}
}
environment {
BLUE_OCEAN_URL = "https://jenkins.infra.ozg-cloud.systems/job/xta-test-server/job/${env.BRANCH_NAME}/${env.BUILD_NUMBER}/"
RELEASE_REGEX = /\d+.\d+.\d+/
SNAPSHOT_REGEX = /\d+.\d+.\d+-SNAPSHOT/
FAILED_STAGE = ""
SH_SUCCESS_STATUS_CODE = 0
}
options {
timeout(time: 1, unit: 'HOURS')
disableConcurrentBuilds()
buildDiscarder(logRotator(numToKeepStr: '5'))
}
stages {
stage('Check Version') {
steps {
script {
FAILED_STAGE = env.STAGE_NAME
def rootVersion = getPomVersion()
if(isReleaseBranch()){
if ( !(rootVersion ==~ RELEASE_REGEX)) {
error("Keine Release Version für Branch ${env.BRANCH_NAME}.")
}
} else {
if ( !(rootVersion ==~ SNAPSHOT_REGEX)) {
error("Keine Snapshot Version für Branch ${env.BRANCH_NAME}.")
}
}
}
}
}
stage('Set Version') {
when {
not {
anyOf {
branch 'master'
branch 'release'
}
}
}
steps {
script {
FAILED_STAGE=env.STAGE_NAME
JAR_TAG = getPomVersion().replace("SNAPSHOT", "${env.BRANCH_NAME}-SNAPSHOT")
}
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
sh "mvn -s $MAVEN_SETTINGS versions:set -DnewVersion=${JAR_TAG} -DprocessAllModules=true"
}
}
}
stage('Build XtaTestServer') {
steps {
script {
FAILED_STAGE=env.STAGE_NAME
}
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
sh 'mvn --no-transfer-progress -s $MAVEN_SETTINGS clean install -Dmaven.wagon.http.retryHandler.count=3 -DelasticTests.disabled=true'
}
}
}
stage('Deploy to Nexus'){
steps {
script {
FAILED_STAGE = env.STAGE_NAME
}
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
sh 'mvn --no-transfer-progress -s $MAVEN_SETTINGS -P nexus-deploy -DskipTests deploy -Dmaven.wagon.http.retryHandler.count=3'
sh "mvn -s $MAVEN_SETTINGS versions:revert"
}
}
}
stage('Build Docker image') {
steps {
script {
FAILED_STAGE=env.STAGE_NAME
}
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
sh 'mvn --no-transfer-progress -s $MAVEN_SETTINGS spring-boot:build-image -DskipTests -Dmaven.wagon.http.retryHandler.count=3'
}
}
}
stage('Tag and Push Docker image') {
steps {
script {
FAILED_STAGE=env.STAGE_NAME
IMAGE_TAG = buildVersionName()
tagAndPushDockerImage(IMAGE_TAG)
if (env.BRANCH_NAME == 'master') {
tagAndPushDockerImage('snapshot-latest')
}
else if (env.BRANCH_NAME == 'release') {
tagAndPushDockerImage('latest')
}
}
}
}
stage('Test, build and deploy Helm Chart') {
steps {
script {
FAILED_STAGE=env.STAGE_NAME
HELM_CHART_VERSION = buildVersionName()
sh "./run_helm_test.sh"
dir('src/main/helm') {
sh "helm package --version=${HELM_CHART_VERSION} ."
deployHelmChart(HELM_CHART_VERSION)
}
}
}
}
stage('Trigger Dev rollout') {
// TODO reactivate before merge
//when {
//branch 'master'
//}
steps {
script {
FAILED_STAGE = env.STAGE_NAME
cloneGitopsRepo()
setNewDevXtaTestServerVersion()
pushDevGitopsRepo()
}
}
}
stage('Trigger Test rollout') {
when {
branch 'release'
}
steps {
script {
FAILED_STAGE = env.STAGE_NAME
cloneGitopsRepo()
setNewTestXtaTestServerVersion()
pushTestGitopsRepo()
}
}
}
stage ('Deploy SBOM to DependencyTrack') {
steps {
script {
IMAGE_TAG = buildVersionName()
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
withCredentials([string(credentialsId: 'dependency-track-api-key', variable: 'API_KEY')]) {
catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE') {
sh "mvn --no-transfer-progress -s $MAVEN_SETTINGS io.github.pmckeown:dependency-track-maven-plugin:upload-bom -Ddependency-track.apiKey=$API_KEY -Ddependency-track.projectVersion=${IMAGE_TAG} -Ddependency-track.dependencyTrackBaseUrl=https://dependency-track.ozg-sh.de"
}
}
}
}
}
}
stage('Sonar Checks') {
when {
branch 'master'
}
steps {
script {
FAILED_STAGE=env.STAGE_NAME
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
try {
withSonarQubeEnv('sonarqube-ozg-sh'){
sh 'mvn -s $MAVEN_SETTINGS sonar:sonar'
}
} catch (Exception e) {
unstable("SonarQube failed")
}
}
}
}
}
}
post {
always{
junit testResults: '**/target/surefire-reports/*.xml', skipPublishingChecks: true
}
failure {
script {
if (env.BRANCH_NAME == 'master' || env.BRANCH_NAME == 'release') {
sendFailureMessage()
}
}
}
}
}
Boolean isReleaseBranch() {
return env.BRANCH_NAME == 'release'
}
String getPomVersion(){
def pom = readMavenPom file: 'pom.xml'
return pom.version
}
Void sendFailureMessage() {
def room = ''
def data = """{"msgtype":"m.text", \
"body":"XtaTestServer: Build Failed. Stage: ${FAILED_STAGE} Build-ID: ${env.BUILD_NUMBER}
Link: ${BLUE_OCEAN_URL}", \
"format": "org.matrix.custom.html", \
"formatted_body":"XtaTestServer: Build Failed. Stage: ${FAILED_STAGE} Build-ID: <a
href='${BLUE_OCEAN_URL}'>${env.BUILD_NUMBER}</a>"}"""
if (env.BRANCH_NAME == 'master') {
room = "!GjqhmouBtnDbwUkAjx:matrix.ozg-sh.de"
}
else if (env.BRANCH_NAME == 'release') {
room = "!oWZpUGTFsxkJIYNfYg:matrix.ozg-sh.de"
}
sh "curl -XPOST -H 'authorization: Bearer ${getElementAccessToken()}' -d '${data}' https://matrix.ozg-sh.de/_matrix/client/v3/rooms/$room/send/m.room.message"
}
String getElementAccessToken() {
withCredentials([string(credentialsId: 'element-login-json', variable: 'LOGIN_JSON')]) {
return readJSON ( text: sh (script: '''curl -XPOST -d \"$LOGIN_JSON\" https://matrix.ozg-sh.de/_matrix/client/v3/login''', returnStdout: true)).access_token
}
}
Void deployHelmChart(String helmChartVersion) {
withCredentials([usernamePassword(credentialsId: 'jenkins-nexus-login', usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD')]){
result = sh script: '''curl -u $USERNAME:$PASSWORD https://nexus.ozg-sh.de/service/rest/v1/components?repository=''' + getHelmChartRepository() + ''' -F file=@xta-test-server-'''+helmChartVersion+'''.tgz''', returnStdout: true
if (result != '') {
error(result)
}
}
}
String getHelmChartRepository(){
if (env.BRANCH_NAME == 'release') {
return 'ozg-base-apps'
}
return 'ozg-base-apps-snapshot'
}
Void loginToDockerRepo() {
withCredentials([usernamePassword(credentialsId: 'jenkins-nexus-login', usernameVariable: 'USER', passwordVariable: 'PASSWORD')]) {
sh 'docker login docker.ozg-sh.de -u ${USER} -p ${PASSWORD}'
}
}
String buildVersionName() {
if (isReleaseBranch()) {
return getPomVersion()
}
return "${getPomVersion()}-${env.BRANCH_NAME}-${env.GIT_COMMIT.take(7)}".replaceAll("_", "-")
}
Void tagAndPushDockerImage(String newTag){
withCredentials([usernamePassword(credentialsId: 'jenkins-nexus-login', usernameVariable: 'USER', passwordVariable: 'PASSWORD')]) {
sh "chmod +x script/push-docker-image.sh"
sh """
export DOCKER_USER=${USER}
export DOCKER_PASSWORD=${PASSWORD}
export BRANCH_NAME=${env.BRANCH_NAME}
./script/push-docker-image.sh ${newTag} ${getPomVersion()}
"""
}
}
Void configureGit() {
final email = "jenkins@ozg-sh.de"
final name = "jenkins"
dir("gitops") {
sh "git config user.email '${email}'"
sh "git config user.name '${name}'"
}
}
Void cloneGitopsRepo() {
withCredentials([usernamePassword(credentialsId: 'jenkins-gitea-access-token', passwordVariable: 'TOKEN', usernameVariable: 'USER')]) {
sh 'git clone https://${USER}:${TOKEN}@git.ozg-sh.de/ozgcloud-devops/gitops.git'
}
configureGit()
}
Void setNewDevXtaTestServerVersion() {
setNewXtaTestServerGitopsVersion("dev")
}
Void setNewTestXtaTestServerVersion() {
setNewXtaTestServerGitopsVersion("test")
}
Void setNewXtaTestServerGitopsVersion(String environment) {
dir("gitops") {
def envFile = "${environment}/application/values/xta-test-server-values.yaml"
def envVersions = readYaml file: envFile
envVersions.xta_test_server.image.tag = IMAGE_TAG
envVersions.xta_test_server.helm.version = HELM_CHART_VERSION
writeYaml file: envFile, data: envVersions, overwrite: true
}
}
Void pushDevGitopsRepo() {
pushNewGitopsVersion('dev')
}
Void pushTestGitopsRepo() {
pushNewGitopsVersion('test')
}
Void pushNewGitopsVersion(String environment) {
dir('gitops') {
if (!hasXtaTestServerValuesFileChanged(environment)) {
return
}
withCredentials([usernamePassword(credentialsId: 'jenkins-gitea-access-token', passwordVariable: 'TOKEN', usernameVariable: 'USER')]) {
sh "git add ${environment}/application/values/xta-test-server-values.yaml"
sh "git commit -m 'jenkins rollout ${environment} aggregation manager version ${IMAGE_TAG}'"
sh 'git push https://${USER}:${TOKEN}@git.ozg-sh.de/ozgcloud-devops/gitops.git'
}
}
}
Boolean hasXtaTestServerValuesFileChanged(String environment) {
return sh (script: "git status | grep '${environment}/application/values/xta-test-server-values.yaml'", returnStatus: true) == env.SH_SUCCESS_STATUS_CODE as Integer
}
<assembly xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
<id>xta2v3</id>
<formats>
<format>zip</format>
</formats>
<baseDirectory>${project.artifactId}</baseDirectory>
<includeBaseDirectory>true</includeBaseDirectory>
<fileSets>
<fileSet>
<directory>${project.build.directory}/pdf</directory>
<outputDirectory>pdf</outputDirectory>
<includes>
<include>*.pdf</include>
</includes>
</fileSet>
<fileSet>
<directory>${project.build.directory}/html</directory>
<outputDirectory>html</outputDirectory>
<includes>
<include>*.html</include>
<include>images/*.png</include>
<include>puml/*.svg</include>
</includes>
</fileSet>
<fileSet>
<directory>${project.basedir}/src/main/resources/store</directory>
<outputDirectory>/</outputDirectory>
<includes>
<include>xta-test-client-john-smith_keystore.p12</include>
<include>xta-test-server_keystore.p12</include>
<include>xta-test_truststore.jks</include>
</includes>
</fileSet>
</fileSets>
<files>
<file>
<source>${project.build.directory}/${project.artifactId}-${project.version}.jar</source>
<outputDirectory>/</outputDirectory>
</file>
<file>
<source>${project.basedir}/build/resources/application-local.yml</source>
<outputDirectory>/</outputDirectory>
</file>
</files>
</assembly>
\ No newline at end of file
# Konfiguration für den XTA-Server
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 10MB
server:
port: 8443
tomcat.max-http-post-size: 10MB
tomcat.max-swallow-size: 10MB
ssl:
# enthaelt den privaten und oeffentlichen Schluessel der Anwendung (SSL-Zertifikat für Webbrowser)
key-store: ./xta-test-server_keystore.p12
key-store-password: password
key-store-type: pkcs12
# Alias im KeyStore
key-alias: xta-test-server
key-password: password
# enthaelt alle vertrauenswuerdigen Zertifikate oder Oberzertifikate
trust-store: ./xta-test_truststore.jks
trust-store-password: password
trust-store-type: JKS
client-auth: want
app:
server:
# Extra Port, auf welchem der Server hören soll (für http)
http-port: 8080
logging:
level:
ROOT: INFO
# no auto configuration report
org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener: INFO
org.springframework.security: WARN
org.springframework.web: INFO
org.apache.cxf: INFO
= Bedienungsanleitung
:toc:
:toc-title: Inhalt
:toclevels: 3
:docinfo: shared
In diesem Dokument wird die Verwendung der XTA Test Applikation beschrieben.
== Starten der Anwendung
=== Voraussetzungen
Zum Starten der Anwendung wird mindestens ein Java in der Version 21 benötigt. Ist keine
entsprechende Java Version verfügbar, dann kann von der https://adoptium.net/[Adoptium]
Seite ein OpenJDK heruntergeladen werden.
Können nicht die mitgelieferten Zertifikate und Keystores verwendet werden, dann sind in
der Datei *application-local.yml* die entsprechenden Konfigurationsparameter anzupassen.
Das Erstellen von KeyStores und TrustStores ist innerhalb des Themas
xref:erstellen_von_zertifikaten.adoc["Erstellen von Zertifikaten"] beschrieben.
=== Konfigurationsparameter
Die Konfiguration ist in der *application-local.yml* und einer *config.yaml* Datei abgelegt. Die Anwendung verwendet den Port 8080
und den Port 8443 als Standard. Sind diese Ports schon belegt, dann sind die entsprechenden
Konfigurationsparameter anzupassen. Sofern die Datei *config.yaml* nicht existiert, so wird diese beim ersten Start der Anwendung erstellt.
==== Konfiguration in der application*.yml
|===
| Konfigurationsparameter | Beschreibung
| server.port | Https Port der Anwendung
| server.ssl.key-store | Pfad zum KeyStore. Dieser enthält den privaten und öffentlichen Schlüssel der Anwendung
| server.ssl.key-store-password | Passwort des KeyStores
| server.ssl.key-alias | Alias im KeyStore
| server.ssl.key-password | Passwort für den Schlüssel im KeyStore
| server.ssl.trust-store | Pfad zum TrustStore. Dieser enthält alle vertrauenswürdigen Zertifikate oder Oberzertifikate
| server.ssl.trust-store-password | Password des TrustStores
| app.server.http-port | Http Port der Anwendung
| logging.level.ROOT | Generelles Log-Level der Anwendung
| logging.level.<Paketname> | Loglevel für ein Paket und dessen Kinder festlegen
|===
==== Konfiguration in der config.yaml
|===
| Konfigurationsparameter | Beschreibung
| protocolMetadata.softwareManufacturer | Hersteller des zu testenden Produkts
| protocolMetadata.softwareName | Name des zu testenden Produkts
| protocolMetadata.softwareVersion | Version des zu testenden Produkts
| protocolMetadata.street | Firmenadresse (Straße) des Herstellers des zu testenden Produktes
| protocolMetadata.streetNo | Firmenadresse (Hausnummer) des Herstellers des zu testenden Produktes
| protocolMetadata.zipCode | Firmenadresse (Postleitzahl) des Herstellers des zu testenden Produktes
| protocolMetadata.city | Firmenadresse (Stadt) des Herstellers des zu testenden Produktes
| protocolMetadata.addressAddition | Firmenadresse (Zusatzangaben) des Herstellers des zu testenden Produktes
| clientProperties.serverUrl.managementPort | Url zum Management-Port des zu testenden Produkts
| clientProperties.serverUrl.sendPort | Url zum Send-Port des zu testenden Produkts
| clientProperties.serverUrl.msgBoxPort | Url zum Messagebox-Port des zu testenden Produkts
| clientProperties.checkHostnameInCertificate | Soll der Hostname im Server Zertifikat geprüft werden (default=true)
| clientProperties.keyStore | Pfad zum KeyStore. Dieser enthält den privaten und öffentlichen Schlüssel des Clients
| clientProperties.keyStorePassword | Passwort des KeyStores
| clientProperties.keyPassword | Passwort für den Schlüssel im KeyStore
| clientProperties.keyAlias | Alias im KeyStore
| clientProperties.trustStore | Pfad zum TrustStore. Dieser enthält das vertrauenswürdige Zertifikat des Servers oder ein Oberzertifikat
| clientProperties.trustStorePassword | Password des TrustStores
| authorIdentifierConfig.identifierScheme | Ausweisung des Schemas zur Interpretation des PartyIdentifiers/Bezeichners, z.B. iso6523-actorid-upis für Peppol Participant Identifier Scheme.
| authorIdentifierConfig.name | Optionaler menschenlesbarer Name zur Darstellung in User Agents (bekannt z.B. aus eMail). Im XÖV-Umfeld muss hier der Name der Behörde / öffentlichen Stelle eingetragen werden.
| authorIdentifierConfig.value | Eindeutige Identifikation eines Kommunikationspartners anhand einer Kennung. Im XÖV-Umfeld muss hier die eindeutige Kennzeichnung der Behörde eingetragen werden.
| authorIdentifierConfig.organizationCategory | Fachkategorie des identifizierten Kommunikationspartners innerhalb der Domäne.
| readerIdentifierConfig.identifierScheme | Ausweisung des Schemas zur Interpretation des PartyIdentifiers/Bezeichners, z.B. iso6523-actorid-upis für Peppol Participant Identifier Scheme.
| readerIdentifierConfig.name | Optionaler menschenlesbarer Name zur Darstellung in User Agents (bekannt z.B. aus eMail). Im XÖV-Umfeld muss hier der Name der Behörde / öffentlichen Stelle eingetragen werden.
| readerIdentifierConfig.value | Eindeutige Identifikation eines Kommunikationspartners anhand einer Kennung. Im XÖV-Umfeld muss hier die eindeutige Kennzeichnung der Behörde eingetragen werden.
| readerIdentifierConfig.organizationCategory | Fachkategorie des identifizierten Kommunikationspartners innerhalb der Domäne.
| senderIdentifierConfig.identifierScheme | Ausweisung des Schemas zur Interpretation des PartyIdentifiers/Bezeichners, z.B. iso6523-actorid-upis für Peppol Participant Identifier Scheme.
| senderIdentifierConfig.name | Optionaler menschenlesbarer Name zur Darstellung in User Agents (bekannt z.B. aus eMail). Im XÖV-Umfeld muss hier der Name der Behörde / öffentlichen Stelle eingetragen werden.
| senderIdentifierConfig.value | Eindeutige Identifikation eines Kommunikationspartners anhand einer Kennung. Im XÖV-Umfeld muss hier die eindeutige Kennzeichnung der Behörde eingetragen werden.
| senderIdentifierConfig.organizationCategory |Fachkategorie des identifizierten Kommunikationspartners innerhalb der Domäne.
| lookupServiceUri | Beim Methodenaufruf "lookupService" aus dem XTA Standard wird der angegebene Service URI verwendet.
| deliveryAttributesServiceQuality | Das Element ServiceQuality ist vorgesehen, um in den Daten des Transportauftrags die Service Qualitäten ansprechen zu können, die bei der Ausführung des Transportauftrags zu berücksichtigen sind.
| qualifierConfig.qualifierSubject | Dieses optionale Element bietet Raum für informatorischen Begleittext.
| qualifierConfig.qualifierService | Spezifischer Dienst im Kontext eines bestimmten Geschäftsfalls.
| qualifierConfig.messageTypeCode | Nachrichtentypen werden über Codes aus Listen definiert
| qualifierConfig.messageTypeListUri | Codeliste von Nachrichtentypen
| qualifierConfig.messageTypeListVersionId | Version der Codeliste
| qualifierConfig.messageTypePayloadSchema | Angabe des Namespace für den Nachrichtentyp als URI
| qualifierConfig.businessScenarioUndefined | Achtung: wenn ausgefüllt, werden die restlichen Angaben zum Geschäftsszenario ignoriert! Freitextliche Angabe eines nicht in einer Codeliste definierten Geschäftsszenarios.
| qualifierConfig.businessScenarioCode | Code innerhalb der Codeliste, um das Szenario zu bestimmen
| qualifierConfig.businessScenarioListUri | Pfad zum Dokument, mit welchem das Szenario definiert wird (Codeliste)
| qualifierConfig.businessScenarioListVersionId | Version der Codeliste
|===
=== Start
Eine Konsole im Programmordner starten und folgendes Kommando ausführen. Der Platzhalter
ist mit der jeweiligen Version zu ersetzen.
----
java -jar xta-test-server-[VERSION].jar --spring.config.import=file:./application-local.yml
----
Sofern mehrere Umgebungen gleichzeitig gestartet werden sollen, so kann man sowohl die *application-xxx.yml*, als auch die
genutzte Serverkonfiguration beim Start der Anwendung mitgeben.
----
java -jar xta-test-server-[VERSION].jar --spring.config.import=file:./application-local.yml -DconfigFileName=file:config_second.yaml
----
Der Parameter "-DconfigFileName=file:config_second.yaml" ist wie folgt aufgebaut:
- -D: Angabe eines Startparameters für die Anwendung
- configFileName: Parameter, welcher gesetzt werden soll
- file:config_second.yaml: "file" bedeutet nutze eine lokale Datei, "config_second.yaml" ist der Name der zu nutzenden Config-Datei.
Nachdem der Server gestartet ist, kann die Benutzeroberfläche über http://localhost:8080
oder https://localhost:8443 geöffnet werden. Wurde der Port geändert, so ist dieser in
entsprechen in der Url anzupassen.
== Benutzeroberfläche
Die XTA Test Applikation besitzt eine Weboberfläche, über die die Anwendung konfiguriert
und gesteuert wird.
.Menüs
* <<Menue-Steuerung, Steuerung>>
* <<Menue-Einstellungen, Einstellungen>>
* <<Menue-Anpassung, Content-Anpassung>>
* <<Menue-Report, Report>>
=== Steuerung [[Menue-Steuerung]]
.Abschnitt Report
Über den Button "Report zurücksetzen" kann ein Report gelöscht/zurückgesetzt werden.
.Abschnitt Szenario
Szenarien können hier ausgewählt und gestartet werden. Nach der Auswahl eines Szenarios
wird darunter eine entsprechende Beschreibung angezeigt. Die Beschreibung enthält welche
Rolle die XTA Test Applikation einnimmt.
Nachdem ein Szenario gestartet wurde, ist es möglich dieses über den Button "Aktuelles
Szenario Neustarten" zurückzusetzen.
=== Einstellungen [[Menue-Einstellungen]]
In diesem Menü können die folgenden Informationen angepasst werden:
* Protokolleinstellungen
* Verbindungseinstellungen
* Endpunkte
Die Einstellungen werden über die Laufzeit des Programmes hinweg gespeichert und müssen nicht
bei jedem Neustart neu eingegeben werden.
.Protokolleinstellungen
Hier kann der Softwarehersteller und das Produkt für den Report konfiguriert
werden.
.Verbindungseinstellungen
Hier können die Parameter für die Vertrauensstellung der Software und die Client-Zertifikate
konfiguriert werden. Ebenso kann die Prüfung auf korrekte Hostnamen aktiviert oder deaktiviert werden.
.Endpunkte
In diesem Menüpunkt können die zu nutzenden Endpunkte angepasst werden, welche für die Kommunikation
als XTA-Client genutzt werden sollen. Die URL sollten in einer Vertrauenstellung mit dem XTA-Server sein
um keine Zertifikatsfehler hervorzurufen. Die Endpunkte sind generell ohne den Zusatz "?wsdl" anzugeben.
=== Content-Konfiguration [[Menue-Anpassung]]
In diesem Abschnitt kann der Inhalt des Generic Content Containers für den Nachrichtenversand
angepasst werden. Die Einstellungen, welche hier getroffen werden, werden in allen
Antworten / Anfragen von Client und Server verwendet.
Man hat die Möglichkeit, zwischen einem Standardcontainer und einem angepassten Container
zu wählen. Der Standardcontainer ist in der Anwendung vordefiniert und kann über den
Button „Vorschau herunterladen“ eingesehen werden. Bei dem angepassten Container hat man
selbst die Möglichkeit, unverschlüsselte oder verschlüsselte Container zu erstellen.
Dazu müssen die entsprechenden Parameter in der Eingabemaske eingetragen und gespeichert
werden. Den gespeicherten Container kann man sich über „Vorschau herunterladen“ anzeigen
lassen.
=== Report [[Menue-Report]]
Zeigt den XTA Konformitätsbericht. Dieser kann über Drucken in ein PDF Dokument überführt
werden.
== Nutzung der Schnittstellen
Nach dem Start der Testumgebung sind die Schnittstellen unter Url http://localhost:8080/MB_XTA-WS
bzw. https://localhost:8443/MB_XTA-WS aufrufbar, sofern die Standardkonfiguration verwendet wurde.
Für die unterschiedlichen Ports des XTA-Service sind unter der genannten Adresse alle Serviceadressen genannt.
Die Testumgebung prüft bei jeder Anfrage, ob alle Sicherheitseinstellungen (Policies) eingehalten wurden. Sofern eine oder mehrere nicht
eingehalten wurde, so wird ein SOAP-Fault mit der entsprechenden Beschreibung zurück gegeben.
Die einzuhalten Policies sind aktuell:
- WS-Adressing
- MTOM (SOAP Message Transmission Optimization Mechanism)
- Nutzung von HTTPS
- Gegebenenfalls muss bei Antworten eine Signaturbestätigung (SignatureConfirmation) mit gesendet werden
=== Aufruf der WSDL-Datei
Die WSDL-Datei ist immer unter der Adresse des Services mit dem Zusatz ?wsdl aufrufbar (z.B. https://localhost:8443/services/XTAService/ManagementPort?wsdl ).
=== HTTPS Kommunikation
Für die Kommunikation mittels HTTPs ist ein Client-Zertifikat notwendig, um den Client gegenüber der Testumgebung zu authentifizieren. Innerhalb der ZIP-Dateien der Testumgebung sind bereits mehrere Zertifikate und Keystores hinterlegt, die für die Kommunikation mit der Testumgebung genutzt werden können:
* xta-test-client-john-smith_keystore.p12 - Dieser Keystore beinhaltet ein Client-Zertifikat, das für die Kommunikation mit der Testumgebung verwendet werden kann. Sofern die Testumgebung in der Standardkonfiguration gestartet wurde, stuft die Umgebung das Zertifikat als vertrauenswürdig ein.
=== Test mit SoapUI
Um einfache XTA-Anfragen mit der Testumgebung zu testen kann das Tool SoapUI mit dem im Ordner "soapui" liegenden Beispielprojekt verwendet werden. Für eine erfolgreiche Herstellung einer HTTPs-Verbindung muss das Client-Zertifikat in den Einstellungen hinterlegt werden.
Dieses Zertifikat wird anschließend für alle Requests genutzt.
image:./images/soapui_cert.png["Notwendige Einstellungen für Client-Zertifikate in SoapUI"]
<p class="footer-text">
<!-- We can use document attributes: -->
Copyright © 2021-{docyear} Koordinierungsstelle für IT-Standards (KoSIT) | <a href="https://www.xoev.de/">https://www.xoev.de</a>
</p>
\ No newline at end of file
<style>
/* Change CSS overflow for table of contents. */
#toc.toc2, #toc { overflow: scroll; }
/* Change styling for footer text. */
.footer-text {
color: rgba(255,255,255,.8);
background: rgba(0,0,0,.8);
padding-left: 1.25em;
}
.footer-text>a:link, .footer-text>a:visited {
color: rgba(255,255,255,.8);
}
#footer-text {
padding-bottom: 0;
}
</style>
\ No newline at end of file
= Erstellen von Zertifikaten
:toc:
:toc-title: Inhalt
:toclevels: 3
:docinfo: shared
== Tools
Für die einfache Erstellung der Privaten Schlüssel, der Zertifikate und der Zertifikatspeicher können folgende Tools verwendet werden.
* https://hohnstaedt.de/xca/[XCA]
* https://keystore-explorer.org/[KeyStore Explorer]
Wer mit OpenSSL und dem Java Keytool vertraut ist, kann auch diese Programme für die Erzeugung der benötigten Dateien verwenden.
Im folgenden ist die Erstellung mit den oben genannten Tools beschrieben.
== Erstellen einer CA mit XCA
Das XCA Programm öffnen und eine neue Datenbank erstellen (Menü -> Datei -> Neue Datenbank).
=== Vorlagen
Damit nicht bei jedem Zertifikat erneut die richtigen Einstellungen getroffen und alle benötigten Felder ausgefüllt werden müssen können Vorlagen angelegt werden.
Wir legen uns für die Root CA, für die Applikation (Server) und für die Clients Vorlagen an.
==== Vorlage für Root CA
Im Tab Vorlagen den Button "Neue Vorlagen" wählen. Im Auswahldialog "[default] CA" wählen.
Die Vorlage entsprechend der Screenshots ausfüllen.
.Tab Inhaber
image:./images/xca_template_root_ca_01.png["Tab Inhaber"]
.Tab Erweiterungen
image:./images/xca_template_root_ca_02.png["Tab Erweiterungen"]
.Tab Schlüsselverwendung
image:./images/xca_template_root_ca_03.png["Tab Schlüsselverwendung"]
.Tab Netscape
image:./images/xca_template_root_ca_04.png["Tab Netscape"]
.Tab Erweitert
Hier sollte kein Text in rot enthalten sein.
.Tab Kommentar
Ein ggf. enthaltener Kommentar kann entfernt werden.
==== Vorlage für die Applikation
Im Tab Vorlagen den Button "Neue Vorlagen" wählen. Im Auswahldialog "[default] TLS_server" wählen.
Die Vorlage entsprechend der Screenshots ausfüllen.
.Tab Inhaber
image:./images/xca_template_app_01.png["Tab Inhaber"]
.Tab Erweiterungen
Unter "X509v3 Subject Alternative Name" alle alternativen DNS Namen eintragen (inkl. IPs). Wurde ein gültiger Domainname als "commonName" eingetragen,
dann kann dieser mit "DNS:copycn" übernommen werden.
image:./images/xca_template_app_02.png["Tab Erweiterungen"]
.Tab Schlüsselverwendung
image:./images/xca_template_app_03.png["Tab Schlüsselverwendung"]
.Tab Netscape
image:./images/xca_template_app_04.png["Tab Netscape"]
.Tab Erweitert
Hier sollte kein Text in rot enthalten sein.
.Tab Kommentar
Ein ggf. enthaltener Kommentar kann entfernt werden.
==== Vorlage für die Clients
Im Tab Vorlagen den Button "Neue Vorlagen" wählen. Im Auswahldialog "[default] TLS_client" wählen.
Die Vorlage entsprechend der Screenshots ausfüllen.
.Tab Inhaber
Im Feld "commonName" den Benutzernamen und in das Feld "emailAddress" dessen Email Adresse eintragen.
image:./images/xca_template_client_01.png[Tab Inhaber]
.Tab Erweiterungen
image:./images/xca_template_client_02.png[Tab Erweiterungen]
.Tab Schlüsselverwendung
image:./images/xca_template_client_03.png[Tab Schlüsselverwendung]
.Tab Netscape
image:./images/xca_template_client_04.png[Tab Netscape]
.Tab Erweitert
Hier sollte kein Text in rot enthalten sein.
.Tab Kommentar
Ein ggf. enthaltener Kommentar kann entfernt werden.
=== Erstellen der Zertifikate
==== Zertifikat der Root CA
Im Tab "Zertifikate" den Button "Neues Zertifikat" wählen.
Das Zertifikat entsprechend der Screenshots ausfüllen.
.Tab Herkunft
In der Auswahl "Vorlage für das neue Zertifikat" die Vorlage "Root CA" auswählen und anschließend auf den Button "Alles übernehmen" drücken.
Jetzt wurden alle Felder mit den Werten der Vorlage befüllt.
image:./images/xca_create_certificate_root_ca_01.png[Tab Herkunft]
.Tab Inhaber
Zuerst im Feld "Interner Name" "XTA Tester Root CA" eintragen. Anschließend über den Button "Erstelle einen neuen Schlüssel" einen neuen Privaten Schlüssel erzeugen.
image:./images/xca_create_certificate_root_ca_02.png[Tab Inhaber]
Nachdem der neue Schlüssel erstellt wurde sollte dieser im Auswahlfeld "Privater Schlüssel" automatisch ausgewählt sein.
image:./images/xca_create_certificate_root_ca_03.png[Tab Inhaber]
Weitere Anpassungen sind nicht notwendig und das Zertifikat kann erstellt werden.
==== Zertifikat der Applikation
Im Tab "Zertifikate" den Button "Neues Zertifikat" wählen.
Das Zertifikat entsprechend der Screenshots ausfüllen.
.Tab Herkunft
In der Gruppe "Unterschreiben" die Option "Verwende dieses Zertifikat zum Unterschreiben" wählen und die Root CA auswählen.
In der Auswahl "Vorlage für das neue Zertifikat" die Vorlage "XTA Tester Application" auswählen und anschließend auf den Button "Alles übernehmen" drücken.
Jetzt wurden alle Felder mit den Werten der Vorlage befüllt.
image:./images/xca_create_certificate_app_01.png[Tab Herkunft]
.Tab Inhaber
Zuerst im Feld "Interner Name" "XTA Tester Application" eintragen. Anschließend über den Button "Erstelle einen neuen Schlüssel" einen neuen Privaten Schlüssel erzeugen.
image:./images/xca_create_certificate_app_02.png[Tab Inhaber]
Nachdem der neue Schlüssel erstellt wurde sollte dieser im Auswahlfeld "Privater Schlüssel" automatisch ausgewählt sein.
image:./images/xca_create_certificate_app_03.png[Tab Inhaber]
Weitere Anpassungen sind nicht notwendig und das Zertifikat kann erstellt werden.
==== Zertifikat eines Clients
Im Tab "Zertifikate" den Button "Neues Zertifikat" wählen.
Das Zertifikat entsprechend der Screenshots ausfüllen.
.Tab Herkunft
In der Gruppe "Unterschreiben" die Option "Verwende dieses Zertifikat zum Unterschreiben" wählen und die Root CA auswählen.
In der Auswahl "Vorlage für das neue Zertifikat" die Vorlage "XTA Tester Client" auswählen und anschließend auf den Button "Alles übernehmen" drücken.
Jetzt wurden alle Felder mit den Werten der Vorlage befüllt.
image:./images/xca_create_certificate_client_01.png[Tab Herkunft]
.Tab Inhaber
Zuerst im Feld "Interner Name" "XTA Tester Client [NAME]" eintragen und noch commonName und emailAddress ausfüllen. Anschließend über den Button
"Erstelle einen neuen Schlüssel" einen neuen Privaten Schlüssel erzeugen.
image:./images/xca_create_certificate_client_02.png[Tab Inhaber]
Nachdem der neue Schlüssel erstellt wurde sollte dieser im Auswahlfeld "Privater Schlüssel" automatisch ausgewählt sein.
image:./images/xca_create_certificate_client_03.png[Tab Inhaber]
Weitere Anpassungen sind nicht notwendig und das Zertifikat kann erstellt werden.
== Erstellen des Keystores
.Privaten Schlüssel der Applikation exportieren
In XCA in den Tab "Private Schlüssel" wechseln und den Schlüssel "XTA Tester Application" wählen. Über den Button "Export" öffnet sich ein Export-Dialog.
Den Schlüssel im "PEM" Format unter dem Dateinamen "XTA_Tester_Application.key.pem" exportieren.
.Zertifikat der Applikation exportieren
In XCA in den Tab "Zertifikate" wechseln und das Zertifikat "XTA Tester Application" wählen. Über den Button "Export" öffnet sich ein Export-Dialog.
Als Exportformat "PEM Kette" wählen und das Zertifikat unter dem Dateinamen "XTA_Tester_Application.pem" exportieren.
.Erstellen des Keystores mit dem KeyStore Explorer
Öffnen des *KeyStore Explorers* und einen neuen "PKCS #12" Schlüsselspeicher erzeugen. Anschließend "Schlüsselpaar importieren" wählen. Im sich öffnenden Dialog
"OpenSSL" wählen. Im folgenden Dialog die CheckBox "Verschlüsselter privater Schlüssel" deaktivieren und in die entsprechenden Felder den Pfad zum privaten Schlüssel
und dem Zertifikat eintragen. Nach dem Import als Alias "xta-tester-application" verwenden. Jetzt muss noch ein Passwort vergeben werden.
Zum Abschluss den Keystore noch speichern, auch hier ist ein Passwort anzugeben. Bitte das gleiche Passwort verwenden. Das vergebene Passwort ist später in der
application.yml Datei zu konfigurieren.
== Erstellen des Truststores
.Root CA exportieren
In XCA in den Tab "Zertifikate" wechseln und das Zertifikat "XTA Tester Root CA" wählen. Über den Button "Export" öffnet sich ein Export-Dialog.
Als Exportformat "PEM" wählen und das Zertifikat unter dem Dateinamen "XTA_Tester_Root_CA.crt" exportieren.
.Erstellen des Truststores mit dem KeyStore Explorer
Öffnen des *KeyStore Explorers* und einen neuen "JKS" Schlüsselspeicher erzeugen. Anschließend "Vertrauenswürdiges Zertifikat importieren" wählen. Im sich öffnenden Dialog
das exportierte Zertifikat auswählen und anschließend noch als Alias "XTA Tester Root CA" eintragen. Zum Abschluss den Truststore speichern.
== Erstellen einer p12 Datei für einen Client
Es gibt zwei Möglichkeiten.
Zum einen kann in XCA im Tab "Zertifikate" das Zertifikat inklusive privatem Schlüssel als
p12-Datei exportiert werden. Dabei ist es wichtig den Eintrag mit Zertifizierungskette zu wählen.
Die zweite Möglichkeit ist den privaten Schlüssel und das Zertifikat getrennt zu exportieren und anschließend die p12-Datei mit dem KeyStore
Explorer zu erzeugen.
.Privaten Schlüssel des Clients exportieren
In XCA in den Tab "Private Schlüssel" wechseln und den Schlüssel "XTA Tester Client [Name]" wählen. Über den Button "Export" öffnet sich ein Export-Dialog.
Den Schlüssel im "PEM" Format unter dem Dateinamen "XTA_Tester_Client_[NAME].key.pem" exportieren.
.Zertifikat des Clients exportieren
In XCA in den Tab "Zertifikate" wechseln und das Zertifikat "XTA Tester Client [Name]" wählen. Über den Button "Export" öffnet sich ein Export-Dialog.
Als Exportformat "PEM Kette" wählen und das Zertifikat unter dem Dateinamen "XTA_Tester_Client_[Name].pem" exportieren.
.Erstellen der p12 Datei mit dem KeyStore Explorer
Öffnen des *KeyStore Explorers* und einen neuen "PKCS #12" Schlüsselspeicher erzeugen. Anschließend "Schlüsselpaar importieren" wählen. Im sich öffnenden Dialog
"OpenSSL" wählen. Im folgenden Dialog die CheckBox "Verschlüsselter privater Schlüssel" deaktivieren und in die entsprechenden Felder den Pfad zum privaten Schlüssel
und dem Zertifikat eintragen. Nach dem Import als Alias "\[Name\] \(xta tester root ca\)" verwenden. Jetzt muss noch ein Passwort vergeben werden.
Zum Abschluss den Keystore noch speichern, auch hier ist ein Passwort anzugeben. Bitte das gleiche Passwort verwenden. Das Passwort wird benötigt wenn der Keystore auf
dem Client eingespielt wird.
doc/images/soapui_cert.png

77.5 KiB

doc/images/xca_create_certificate_app_01.png

25.6 KiB

doc/images/xca_create_certificate_app_02.png

11.3 KiB

doc/images/xca_create_certificate_app_03.png

25 KiB

doc/images/xca_create_certificate_client_01.png

25.5 KiB

doc/images/xca_create_certificate_client_02.png

11.4 KiB

doc/images/xca_create_certificate_client_03.png

25 KiB

doc/images/xca_create_certificate_root_ca_01.png

24.2 KiB

doc/images/xca_create_certificate_root_ca_02.png

11.1 KiB

doc/images/xca_create_certificate_root_ca_03.png

24.8 KiB

doc/images/xca_template_app_01.png

23 KiB

0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment