Anmeldung und Tokens

So folgen Sie diesem Kapitel

Eingaben: clientEmail, clientPassword und der zugestellte Verifizierungscode.

Schritte und erwartetes Ergebnis: Der erste Faktor fordert die Verifizierung an; der zweite liefert die Kundensitzung. Speichern Sie nach Anmeldung oder Erneuerung beide Tokens. Abmelden beendet die aktuelle Sitzung.

Alternativen und spätere Aktionen: Verwenden Sie den Anmeldeablauf zum Starten einer Sitzung. Token-Erneuerung und Abmeldung sind spätere Aktionen zur Sitzungsverwaltung.

DTO-Quellcode: AccessTokenOutputModel, AuthenticationSecondFactorOutputModel

In früheren Codeblöcken zugewiesene Variablen werden später wiederverwendet. Kundeneingaben stammen aus Ihrer Oberfläche. Bewahren Sie IDs und Referenzwerte im Kontext des jeweiligen Kunden auf; legen Sie nicht für jeden Schritt einen neuen Kontext an.

Die Beispiele verwenden gemeinsame Hilfsklassen. Lesen Sie Gemeinsame Hilfsklassen: vollständiger C#- und Java-Quellcode bevor Sie ein Beispiel übernehmen.
Voraussetzungen: Vorhandene clientEmail und clientPassword. Beginnen Sie mit einem GUEST-Token und erfassen Sie authenticationCode aus dem eingerichteten zweiten Authentifizierungskanal.
Für den nächsten Schritt aufbewahren: userId und die aktuellen Werte accessToken, refreshToken und validUntil. Speichern Sie nach jeder Erneuerung beide neuen Tokens.
Dieses Kapitel beschreibt die Zwei-Faktor-Authentifizierung. Das Ergebnis ist ein Token mit der Benutzerrolle (CLIENT, SELLER, ADMIN oder SUPERADMIN). Speichern Sie AccessToken, RefreshToken, Id und ValidUntil aus der Antwort. Ablaufzeit und Erneuerungszeitraum werden vom Dienst festgelegt.

Zwei-Faktor-Authentifizierung

Eingaben: E-Mail-Adresse und Passwort des Kunden, anschliessend der zugestellte authenticationCode.
Aktion: Schliessen Sie beide Authentifizierungsfaktoren ab.
Aufbewahren / erwartetes Ergebnis: Speichern Sie userId, accessToken, refreshToken und validUntil aus der abschliessenden Antwort.
Setzen Sie für diesen Aufruf einen GUEST-Token im Authorization-Header. Erfassen Sie nach erfolgreichem ersten Faktor den Verifizierungscode aus dem für das Konto eingerichteten Kanal. In isolierten Testkonfigurationen kann die Antwort den Code ebenfalls enthalten. Beim gezeigten Kundenkonto liefert der zweite Faktor einen CLIENT-Access-Token für weitere Kundenanfragen. 
								
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", guestToken);
// First factor authentication
var payload = JsonConvert.SerializeObject(new { AccountNumber = clientEmail, Password = clientPassword });
(await httpClient.PostAsync("api/v1/users/authentication/first-factor", new StringContent(payload, Encoding.UTF8, "application/json"))).EnsureSuccessStatusCode();
// Collect authenticationCode from the configured second-factor channel.
// Second factor authentication
payload = JsonConvert.SerializeObject(new { AccountNumber = clientEmail, Token = authenticationCode });
var httpResponseMessage = await httpClient.PostAsync("api/v1/users/authentication/second-factor", new StringContent(payload, Encoding.UTF8, "application/json"));
httpResponseMessage.EnsureSuccessStatusCode();
var resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var authenticationResult = JsonConvert.DeserializeObject<AuthenticationSecondFactorOutputModel>(resultAsString);
// Now, set the CLIENT token for the next requests
var userId = authenticationResult.Id;
var accessToken = authenticationResult.AccessToken;
var refreshToken = authenticationResult.RefreshToken;
var validUntil = authenticationResult.ValidUntil;
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);


								
// First factor authentication
JsonObject firstFactorPayload = new JsonObject();
firstFactorPayload.addProperty("AccountNumber", clientEmail);
firstFactorPayload.addProperty("Password", clientPassword);

HttpRequest firstFactorRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/authentication/first-factor"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(firstFactorPayload.toString()))
    .build();

var firstFactorResponse = httpClient.send(firstFactorRequest, BodyHandlers.ofString());
Api.requireSuccess(firstFactorResponse);
// Collect authenticationCode from the configured second-factor channel.

// Second factor authentication
JsonObject secondFactorPayload = new JsonObject();
secondFactorPayload.addProperty("AccountNumber", clientEmail);
secondFactorPayload.addProperty("Token", authenticationCode);

HttpRequest secondFactorRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/authentication/second-factor"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(secondFactorPayload.toString()))
    .build();

var response = httpClient.send(secondFactorRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
AuthenticationSecondFactorOutputModel authenticationResult = new Gson().fromJson(response.body(), AuthenticationSecondFactorOutputModel.class);

// Now, set the CLIENT token for the next requests
var userId = authenticationResult.Id;
var accessToken = authenticationResult.AccessToken;
var refreshToken = authenticationResult.RefreshToken;
var validUntil = authenticationResult.ValidUntil;
Der Zustellungskanal für den zweiten Faktor wird für Konto und Umgebung eingerichtet. Verwenden Sie den vom Kunden erhaltenen Code.

Abmelden

Eingaben: Der aktuelle CLIENT-Access-Token.
Aktion: Beenden Sie die aktuelle Sitzung.
Aufbewahren / erwartetes Ergebnis: Entfernen Sie nach erfolgreicher Abmeldung die gespeicherte Sitzung.
Dieser Vorgang macht den Authentifizierungstoken ungültig.
								
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
(await httpClient.PostAsync("api/v1/users/authentication/logout", null)).EnsureSuccessStatusCode();


								
HttpRequest theRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/authentication/logout"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

var response = httpClient.send(theRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
Ein durch Abmeldung ungültiger Token kann nicht mehr erneuert werden; eine neue Anmeldung ist erforderlich.

Authentifizierungstoken erneuern

Eingaben: userId und das aktuelle Access-/Refresh-Token-Paar.
Aktion: Fordern Sie eine erneuerte Sitzung an.
Aufbewahren / erwartetes Ergebnis: Ersetzen Sie beide gespeicherten Tokens und validUntil durch die zurückgegebenen Werte.
Nach Ablauf des Access-Tokens liefern geschützte Anfragen HTTP 401; der Dienst kann TOKEN-EXPIRED: true zurückgeben. Die Erneuerung benötigt das aktuelle Token-Paar und die Benutzer-ID. Der zulässige Erneuerungszeitraum wird ab dem gespeicherten Erstellungszeitpunkt des Tokens bestimmt; es handelt sich nicht um ein festes Fünf-Minuten-Fenster nach Ablauf.
Autorisieren Sie die Erneuerungsanfrage mit einem gültigen GUEST-Token. Senden Sie das aktuelle Token-Paar im Payload und ersetzen Sie anschliessend beide gespeicherten Tokens durch das neue Paar. Falls die Erneuerung fehlschlägt, melden Sie sich erneut an; wiederholen Sie nicht fortlaufend eine Anfrage mit einem ungültigen Paar.

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", guestToken);
payload = JsonConvert.SerializeObject(new
{
    UserId = userId,
    RefreshToken = refreshToken,
    AccessToken = accessToken
});
httpResponseMessage = await httpClient.PostAsync("api/v1/users/authentication/access-token/refresh", new StringContent(payload, Encoding.UTF8, "application/json"));
httpResponseMessage.EnsureSuccessStatusCode();
resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var accessTokenOutputModel = JsonConvert.DeserializeObject<AccessTokenOutputModel>(resultAsString);
// Set new CLIENT token for the next HTTP requests
accessToken = accessTokenOutputModel.AccessToken;
refreshToken = accessTokenOutputModel.RefreshToken;
validUntil = accessTokenOutputModel.ValidUntil;
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);


								
JsonObject thePayload = new JsonObject();
thePayload.addProperty("UserId", userId);
thePayload.addProperty("RefreshToken", refreshToken);
thePayload.addProperty("AccessToken", accessToken);

HttpRequest theRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/authentication/access-token/refresh"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(thePayload.toString()))
    .build();

var response = httpClient.send(theRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
AccessTokenOutputModel accessTokenOutputModel = new Gson().fromJson(response.body(), AccessTokenOutputModel.class);

// New CLIENT token for the next HTTP requests
accessToken = accessTokenOutputModel.AccessToken;
refreshToken = accessTokenOutputModel.RefreshToken;
validUntil = accessTokenOutputModel.ValidUntil;

Ergebnis erkennen

Nach erfolgreichem zweiten Faktor oder Token-Erneuerung: Ersetzen Sie das gespeicherte Token-Paar. Dies ist ein Ausschnitt der Antwort.

{"id":123,"accessToken":"<access-token>","refreshToken":"<refresh-token>","validUntil":"2026-10-13T12:00:00Z"}

Weitere Antwortfelder finden Sie im DTO-Katalog. Behandeln Sie fehlgeschlagene Anfragen, bevor Sie fortfahren; siehe Fehlerbehandlung.