Authentifizierung gegenüber der Public API

Für was benötige ich eine Authentifizierung?

Über die Micromate Public API erhält der Aufrufer Zugriff auf Daten seiner Micromate-Organisation resp. der Lernenden in der Organisation. Damit die Organisations-Daten von Zugriffen Dritter geschützt sind, ist bei jedem Aufruf der API eine Authentifizierung notwendig.

Das Wichtigste in Kürze

Unabhängig des Authentifizierungs-Mechanismus muss mit jedem Aufruf der Micromate Public API ein gültiges Access Token mitgesendet werden
Micromate unterstützt die Authentifizierungs-Mechanismen Private Key JWT und Client Secret Basic.

Wie funktioniert die Authentifizierung für den Zugriff auf die Micromate Public API?

Die Micromate Public API unterstützt zwei Mechanismen wie sich der Aufrufende gegenüber der API authentifizieren kann:

Soll ich Private Key JWT oder Client Secret Basic verwenden?

Wenn möglich, sollte stets die Authentifizierung mittels Private Key JWT gegenüber der Micromate Public API verwendet werden.

Diese Methode bietet erhebliche Sicherheitsvorteile, da dabei kein Passwort direkt übertragen wird. Dadurch wird das Risiko reduziert, dass Zugangsdaten abgefangen werden können.

Client Secret Basic sollte nur dann eingesetzt werden, wenn das verwendete System (z.B. Microsoft Power Automate) keine Private Key JWT Authentifizierung unterstützt.

Wie funktioniert die Authentifizierung mit Private Key JWT?

Damit du die Public API von Micromate mit dem Private Key JWT Mechanismus aufrufen kannst, musst du ein JWT erstellen und dieses mit dem Schlüssel, welchen du von uns erhalten hast signieren.

Falls du noch keinen Schlüssel erhalten hast, melde dich auf hello@micromate.ai.

Ablauf der Private Key JWT-Authentifizierung

Erstelle ein neues Token mit den Informationen aus dem Private-Key sowie gültigen Ausstell- sowie Ablaufzeiten
Signiere das Token mit dem von uns erhaltenen private Key.
Verwende das Token um über https://login.micromate.ai/oauth/v2/token ein Access Token abzufragen
Verwende das erhaltene Access Token für jeden Aufruf an die Micromate Public API

Typescript Beispiel für NodeJS

Folgend eine Beispielimplementation in Typescript in einer NodeJS-Umgebung:

import * as jsonwebtoken from 'jsonwebtoken';
import fs from 'fs';
import axios from 'axios';
// Sample usage:
// await new MicromateRequest().callMicromatePublicApi();
export class MicromateRequest {
    public async callMicromatePublicApi(): Promise<void> {
        const token = await this.getOAuthToken();
        const data = await axios.get('http://bot.micromate.ai/api/public/organization/{organizationId}/learningPackage/{learningPackageId}/questions', {
            headers: {Authorization: `Bearer ${token}`}
        });
        console.log('Data retrieved from micromate public api: ', data.data);
    }
    private createSignedJWT(): string {
        // Read the private key
        const rawPrivateKey = fs.readFileSync('./privateKey.json', 'utf8');
        const privateKey = JSON.parse(rawPrivateKey) as JWTPrivateKey;
        // Valid from now minus 10 seconds
        const validFrom: number = Math.floor(Date.now() / 1000) - 10;
        // Expiration 1 hour after now
        const expiration: number = Math.floor(Date.now() / 1000) + (60 * 60);
        // Create a JWT token
        const jwtToSign = {
            iss: privateKey.userId,
            sub: privateKey.userId,
            aud: 'https://login.micromate.ai',
            iat: validFrom,
            exp: expiration
        };
        // Sign and return the token
        return jsonwebtoken.sign(jwtToSign, privateKey.key, {algorithm: 'RS256', keyid: privateKey.keyId});
    }
    private async getOAuthToken(): Promise<string> {
        // Create signed token
        const token = this.createSignedJWT();
        // Request to token endpoint to get an access token
        // which then can be used to access the micromate public api
        const data = await axios.post<TokenResponse>('https://login.micromate.ai/oauth/v2/token', {}, {
            params: {
                'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
                'scope': 'openid profile email urn:zitadel:iam:org:project:id:122147021183311927:aud urn:zitadel:iam:org:projects:roles',
                'assertion': token
            },
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            }
        });
        // Return access token
        return data.data.access_token;
    }
}
export interface JWTPrivateKey {
    type: string,
    keyId: string,
    key: string,
    userId: string
}
export interface TokenResponse {
    token_type: string,
    access_token: string,
    expires_in: number
}

PHP Beispiel

Folgend eine Beispielimplementation in PHP um ein Access Token abzufragen:

<?php
// Read private key from file
$privateKey = file_get_contents("privateKey.json");
$privateKeyData = json_decode($privateKey);
$jwtHeader = base64url_encode(json_encode(array(
    "alg" => "RS256",
    "typ" => "JWT",
    "kid" => $privateKeyData->{'keyId'}
)));
$now = time();
$jwtClaim = base64url_encode(json_encode(array(
    "iss" => $privateKeyData->{'userId'},
    "sub" => $privateKeyData->{'userId'},
    "aud" => "https://login.micromate.ai",
    "iat" => $now,
    "exp" => $now + 3600
)));
// Create the data strign we want to have a signature for
$dataToSign = $jwtHeader . "." . $jwtClaim;
// Create the signature for our data
$signature = '';
openssl_sign($dataToSign, $signature, $privateKeyData->{'key'}, 'sha256');
$jwtSign = base64url_encode($signature);
// Concat our data with the created signature --> This is the asseration we can use to authenticate
$jwtAssertion = $dataToSign . "." . $jwtSign;
// Build the content for the OAuth-Token-Request
$content = http_build_query(array(
    "grant_type" => "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "scope" => "openid profile email urn:zitadel:iam:org:project:id:122147021183311927:aud urn:zitadel:iam:org:projects:roles",
    "assertion" => $jwtAssertion
), '', '&');
// Request OAuth-Token
$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => 'Content-Type: application/x-www-form-urlencoded',
        'ignore_errors' => true,
        'content' => $content
    )
));
$result = file_get_contents('https://login.micromate.ai/oauth/v2/token', false, $context);
// Print the OAuth-Token in the format: 
// {"access_token":"<Token>","token_type":"Bearer","expires_in":43199}
echo $result;
function base64url_encode($data)
{
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

Wie funktioniert die Authentifizierung mit Client Secret Basic?

Damit du die Public API von Micromate mit dem Client-Secret-Basic-Mechanismus aufrufen kannst, musst du die Client-ID sowie das Client-Secret bei jedem API-Aufruf im Authorization-Header mitsenden.

Falls du die Client ID sowie das Client Secret noch nicht erhalten hast, melde dich auf hello@micromate.ai.

Ablauf

Erstelle ein Base64-codiertes Token aus der Client-ID und dem Client-Secret.
Füge das erstellte Token bei jedem API-Aufruf im Authorization-Header hinzu.

Typescript Beispiel für NodeJS

import axios from 'axios';

// Sample usage:
// await new MicromateRequest().callMicromatePublicApi();
export class MicromateRequest {
    public async callMicromatePublicApi(): Promise<void> {
        const token = this.getToken();
        const data = await axios.get('http://bot.micromate.ai/api/public/organization/{organizationId}/learningPackage/{learningPackageId}/questions', {
            headers: {Authorization: `Basic ${token}`}
        });
        console.log('Data retrieved from micromate public api: ', data.data);
    }

    private getToken(): string {
        const clientId = ''; // Read from configuration
        const clientSecret = ''; // Read from configuration

        return Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
    }
}