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:
- Einrichten eines Benutzers mit ausreichenden Berechtigungen,
- Authentifizierung am Merkmalservice Keycloak Server und Abrufen eine Access Tokens,
- Beispiele und Skripte:
- 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 dersource
Befehl genutzt werden:source get-access-token.sh username password variable-name
#!/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.@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
<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>
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 UmgebungsvariablenTOKEN
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.