Zum Beantragen einer Web Anwendung Sage ID Client muss nur eine Domain wie z.B. applikation.firma.de bzw. URL application.firma.de/root angegeben werden (base_url). Dann ergeben sich erlaubte Callback URLs und Logout Uris wie unten beschrieben. Wenn Sie individuelle Uris benötigen, kommen Sie auf uns zu. Auf sicherem Weg erhalten Sie Client Id und Client Secret, die wie unten im Flow verwendet werden.

Beantragen Sie Client ID / Client Secret mit folgendem Formular per E-Mail an developer@sage.de.

Callback URLs

Callback URLs müssen abgesichert werden, so erkennt SageID nur erlaubte Uris als gültig an. Um Benutzer zu einer erlaubten Callback URL zurückzubringen, muss Ihre Anwendung wissen, wie sie den Benutzer weiterleiten kann. Per default erlaubte Callback URLs:

https://<base_url>/callback

Logout Uris

Nachdem sich Benutzer abgemeldet haben, können Sie Benutzer zu einer bestimmten Uris weiterleiten. Sie müssen die Umleitung in Ihren Mandanten- oder Anwendungseinstellungen registrieren. SageID leitet nach einer Abmeldung nur zu einer erlaubten Logout Uri weiter. Per default erlaubte Logout Uris:

https://<base_url>/
https://<base_url>/logout

SageID Web Anwendung Konfiguration

In SageID wird für eine beantragte Web Anwendung Client folgendes konfiguriert. Die Konfiguration des SageID Client erfolgt nur durch Sage.

Konfiguration SageID Web Anwendung Client

Zusammenfassung Flow

Um ein Sage ID Access Token zu erhalten von einer Web Applikation, muss Authorization Code OAuth 2.0 grant flow (defined in RFC 6749, section 4.1) implementiert werden. Bei diesem Flow erhält ein Browser ein Authorization Code von Sage ID und sendet diesen an Ihre Web Applikation. Anschließend tauscht die Web Applikation diesen aus mit einem Access Token und optional einem Refresh Token. Ihre Web Applikation kann jetzt diesen Access Token verwenden für Aufrufe gegen die Sage 100.

Dieser OAuth 2.0 Flow hat folgende Schritte:

Ihre Web Applikation initiiert den Flow und redirected den Browser zu Sage ID - dem /authorize Endpunkt. Der Benutzer kann sich anmelden.
Sage ID authentifiziert einen Benutzer über den Browser. Beim ersten mal akzeptiert ein Benutzer einen Consent mit den Berechtigungen, die einer Applikation gegeben werden.
Sage ID leitet einen Benutzer an Ihre Web Applikation weiter mit Authorization Code als Parameter, der redirect_uri wie in /authorize Aufruf gesetzt. Die redirect_uri muss mit der Callback URL für den SageID Client gesetzt sein.
Ihre Web Applikation sendet den Authorization Code an Sage ID und tauscht diesen gegen Access Token und optional Refresh Token aus. Dies wird über den /oauth/token Endpunkt umgesetzt. Ihre Web Applikation authentifiziert sich mit Client Id und Client Secret.
Sage ID authentifiziert Ihre Web Applikation, validiert den Authorization Code und antwortet mit dem Access Token und optional Refresh Token.
Jetzt kann Ihre Web Applikation den Access Token verwenden, um Sage 100 API aufzurufen.

OAuth 2.0 Flow

Folgende Postman Collection enthält OAuth 2.0 Flow auch für die Web Applikation für die noch ein Sage ID Client beantragt werden muss.

Implementierung

In diesem Kapitel werden die Schritte beschrieben, um eine SageID Anmeldung in einer Web Anwendung umzusetzen.

1. Erhalten der Benutzer Token

Um den Authorization Code Flow zu starten, muss eine Web Anwendung den Benutzer zur /authorize Endpunkt redirecten inklusive der code_challenge.

<a href="https://id.sage.com/authorize?audience=s100de/sage100&scope=openid token access_token offline_access email profile&response_type=code&client_id=<IHRE_CLIENT_ID>&redirect_uri=<IHRE_CALLBACK_URL>&state=<IHR_OPAQUE_STATE>
 ">
  Sign In
</a>

2. Austausch des Authorization Code mit einem Access Token

Jetzt kann der Authorization Code ausgetauscht werden mit einem Access Token, um einen Aufruf der Sage 100 API umsetzen zu können. Der Authorization Code vom vorhergehenden Schritt wird verwendet, der an /oauth/token per POST gesendet werden kann.

  var client = new RestSharp.RestClient();
  var request = new RestRequest(new Uri("https://id.sage.com/oauth/token"), Method.Post);
  request.RequestFormat = DataFormat.Json;
  request.AddJsonBody(new
  {
      grant_type = "authorization_code",
      client_id = "IHRE_CLIENT_ID",
      client_secret = "IHR_CLIENT_SECRET",
      code = "IHR_AUTHORIZATION_CODE",
      redirect_uri = "IHRE_REDIRECT_URL"
  });
  RestResponse response = await client.ExecuteAsync(request);

The Antwort enthält access_token, refresh_token, id_token, und token_type. Ein Beispiel:

{
  "access_token":"eyJhbGc...XkRIg",
  "refresh_token":"cqd...KwKfc",
  "id_token":"eyJhb...gupw",
  "scope":"openid profile email offline_access",
  "expires_in":28800,
  "token_type":"Bearer"
}

Der refresh_token wird nur zurückgegeben mit offline_acess scope.

3. Aufruf der Sage 100 API

Mit dem access_token kann die Sage 100 API aufgerufen werden, in dem der Access Token (Bearer) übergeben wird im Authorization Header.

var client = new RestSharp.RestClient();
var request = new RestRequest(new Uri("https://connectivity.sage.de/ws/<IHRE_ENTITLEMENTID>/sdata/<IHRE_SDATA_URL>"), Method.Get);
request.AddHeader("Authorization", "Bearer <Aktueller_Access_Token>");

//weitere Http Header, z.B.
//request.AddHeader("X-Sage-ConnectivityVersion", "1.3"); 
//request.AddHeader("X-ApiEndpoint", "ept<Ihr Endpunkt>");
//...

RestResponse response = await client.ExecuteAsync(request);
return response;

4. Einen neuen Access Token anfragen

Wenn ein refresh_token erhalten wurde, kann der Endpunkt /oauth/token angefragt werden mit dem refresh_token grant_type und dem refresh token, um ein neuen Access Token zu erhalten.

  var client = new RestSharp.RestClient();
  var request = new RestRequest(new Uri("https://id.sage.com/oauth/token"), Method.Post);
  request.RequestFormat = DataFormat.Json;
  request.AddJsonBody(new
  {
      grant_type = "refresh_token",
      refresh_token = "IHR_REFRESH_TOKEN",
      client_id = "IHRE_CLIENT_ID",
      client_secret = "IHR_CLIENT_SECRET",
  });
  RestResponse response = await client.ExecuteAsync(request);

Die Antwort enthält access_token, id_token, scope, expires_in und token_type.

3.2.3 Authentifizierung Web Anwendung