Merkmalservice bietet Zugriff auf Daten über eine GraphQL API. Um Zugriff zu erhalten, muss jedes Request mit einem gültigen Access Token versehen werden.

Es wird ein Keycloak Server für die Benutzer- und Rechteverwaltung sowie Authentifizierung eingesetzt. Dieser bietet breiten OAuth support, etwa Authentifizierung mittels OpenID Connect, OAuth 2.0 und Verwaltung von Benutzerrechten mittels UMA.

Im folgenden ist ein grundlegendes Verständnis von OAuth Prozessen und Begriffen hilfreich, eine hervorragende Kurzeinführung findet sich etwa hier.

Die folgenden Schritte sind nötig um einen neuen Merkmalservice Client zu entwickeln:

1. Einrichten eines Benutzers mit ausreichenden Berechtigungen,
2. Authentifizierung am Merkmalservice Keycloak Server und Abrufen eine Access Tokens,
   • Beispiele und Skripte:
     • Linux Bash
     • Windows Batch
     • Java Keycloak Adapter
3. Datenzugriff mittels GraphQL am Merkmalservice GraphQL Server.

Benutzer anlegen

Für die Authentifizierung wird ein Benutzer Account mit Zugriffsrechten auf die gewünschte Organisation benötigt. Um diesen anzulegen, einfach beim Merkmalservice registrieren, dann durch einen Organisations-Admin entsprechende Zugriffsrechte erteilen.

Authentifizierung

Um auf Merkmalservice Dienste zuzugreifen, ist ein gültiges Access Token erforderlich. Für externe Clients sind momentan ausschließlich OAuth 1/2 Password Grants zugelassen. Bei Bedarf für andere Grant Typen, bitte Kontakt aufnehmen.

Eigenschaft	Wert
Endpunkt:	https://keycloak.researchstudio.at/auth/
Realm:	merkmalservice
Grant Type:	password
Client ID:	merkmalservice-frontend
Client Secret:	keines (Public Client)
User Name:	***
User Passwort:	***

Aktuell sind derart erteilte Access Tokens für 1 Stunde gültig, danach muss ein neues abgerufen werden.

Beispiele und Skripte

Linux Bash

Sollte ihre Linux Distribution kein curl enthalten, installieren Sie dieses, es wird für die folgenden Skripte benötigt.

Verwendung: ./get-access-token.sh username password [variable-name]

Wird variable-name angegeben, dann wird das Token in die entsprechende Umgebunsvariable exportiert, andernfalls wird es an die Standardausgabe ausgegeben. Um exportierte Variablen in die aktuelle Shell zu übernehmen, kann der source Befehl genutzt werden: source get-access-token.sh username password variable-name

get-access-token.sh

#!/bin/bash

AUTH_SERVER="https://keycloak.researchstudio.at/auth"
AUTH_REALM="merkmalservice"
AUTH_CLIENT="merkmalservice-frontend"
USER_NAME="$1"
USER_PWD="$2"

# TODO: remove curl -k parameter when the keycloak server ssl configuration is fixed.

RESULT=`curl -k -s --data "grant_type=password&client_id=$AUTH_CLIENT&username=$USER_NAME&password=$USER_PWD" $AUTH_SERVER/realms/$AUTH_REALM/protocol/openid-connect/token`

if echo $RESULT | grep -q "access_token"
then
  TOKEN=`echo $RESULT | sed 's/.*access_token":"//g' | sed 's/".*//g'`
  if [ "$3" == '' ]
  then
    echo $TOKEN
  else
    export $3=$TOKEN
  fi
else
 echo "error: $RESULT"
fi

Windows Batch

Sollte noch kein curl installiert sein (Windows 10/11 enthalten es bereits), installieren Sie curl für Windows und fügen Sie es zu ihrem Suchpfad hinzu, es wird für die folgenden Skripte benötigt.

Verwendung: get-access-token.bat username password [variable-name]

Wird variable-name angegeben, dann wird das Token an die entsprechende Umgebunsvariable zugewiesen, andernfalls wird es an die Standardausgabe ausgegeben.

get-access-token.bat

@echo off

setlocal

set "AUTH_SERVER=https://keycloak.researchstudio.at/auth"
set "AUTH_REALM=merkmalservice"
set "AUTH_CLIENT=merkmalservice-frontend"
set "USER_NAME=%1"
set "USER_PWD=%2"

for /F "delims=" %%i in ('curl -s --data "grant_type=password&client_id=%AUTH_CLIENT%&username=%USER_NAME%&password=%USER_PWD%" %AUTH_SERVER%/realms/%AUTH_REALM%/protocol/openid-connect/token') do (
  set RESULT=%%i
)

set "JSON=%RESULT:~1,-1%"
set "JSON=%JSON:":=",%"

set mod=0
for %%I in (%JSON%) do (
    set /a mod = !mod
    setlocal enabledelayedexpansion
    if !mod! equ 0 (
        for %%# in ("!var!") do endlocal & set "JSON[%%~#]=%%~I"
    ) else (
        endlocal & set "var=%%~I"
    )
)

if not "%JSON[access_token]%"=="" (
  if "%3"=="" (
    echo %JSON[access_token]%
  ) else (
    endlocal & set "%3=%JSON[access_token]%"
  )
) else (
  echo error: %RESULT%
)

Java Keycloak Adapter

Java Authentifizierungs Beispiel mittels Keycloak Java Adapter (nur AuthZ Komponente erforderlich).

Verwendung: java Sample username password

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>at.researchstudio.sat.merkmalservice.client</groupId>
	<artifactId>java-sample</artifactId>
	<version>1.0</version>
	<packaging>jar</packaging>
	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<maven.compiler.source>11</maven.compiler.source>
		<maven.compiler.target>11</maven.compiler.target>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.keycloak</groupId>
			<artifactId>keycloak-authz-client</artifactId>
			<version>11.0.2</version>
		</dependency>
		<dependency>
			<groupId>org.keycloak</groupId>
			<artifactId>keycloak-adapter-core</artifactId>
			<version>11.0.2</version>
		</dependency>
	</dependencies>
</project>

src/main/java/Sample.java

import java.util.Collections;

import org.keycloak.adapters.HttpClientBuilder;
import org.keycloak.authorization.client.AuthzClient;
import org.keycloak.authorization.client.Configuration;

public class Sample {

    private static final String AUTH_SERVER_URL = "https://keycloak.researchstudio.at/auth";
    private static final String AUTH_REALM = "merkmalservice";
    private static final String AUTH_CLIENT = "merkmalservice-frontend";

    public static void main(String[] args) {
        if (args.length < 2) throw new IllegalArgumentException(
                "Application arguments are missing, you have to specify a user name and password.");

        // TODO remove new HttpClientBuilder().disableTrustManager().build() when the keycloak
        // server ssl configuration is fixed. can be set to null; can also remove keycloak-adapter-core dependency.

        Configuration config = new Configuration(AUTH_SERVER_URL, AUTH_REALM, AUTH_CLIENT,
                Collections.singletonMap("secret", ""),
                new HttpClientBuilder().disableTrustManager().build());
        AuthzClient ac = AuthzClient.create(config);

        String userName = args[0], userPwd = args[1];
        String accessToken = ac.obtainAccessToken(userName, userPwd).getToken();
        System.out.println("Sucessfully authenticated user " + userName + ", got access token: ");
        System.out.println(accessToken);
    }

}

GraphQL Zugriff

Zugriffe auf den Merkmalservice GraphQL Server können mit jeder GraphQL Client Bibliothek über den Endpunkt https://app.merkmalservice.at/backend/graphql erfolgen. Unter graphql.org/code finden sich zahlreiche Bibliotheken für jede Anwendung.

Jedes Merkmalservice Server Request muss mit dem HTTP Header Authorization: bearer {my-access-token} authorisiert werden.

In folgendem Beispiel wird curl verwendet, um alle unterstützten GraphQL Queries vom Merkmalservice GraphQL Server abuzrufen. Ein gültiges Access Token muss in der Umgebungsvariablen TOKEN abgelegt werden, etwa mit einem der obenstehenden Skripte:

   curl https://app.merkmalservice.at/backend/graphql -H "Authorization: bearer $TOKEN" -H 'Content-Type: application/json' -H 'Accept: application/json' --compressed --data-binary '{"query":"{\n\t__schema{\n queryType {\n fields{\n name\n }\n }\n }\n}"}'

Informationen zum Merkmalservice GraphQL Schema sind in Vorbereitung und in Kürze verfügbar.