Öffentliche APIs für die Cloud

»manage it« als

E-Paper 11-12 2011
E-Paper 9-10 2011
E-Paper 5-6 2011
E-Paper 3-4 2011
E-Paper 1-2 2011
E-Paper 11-12 2010
E-Paper 9-10 2010
E-Paper 7-8 2010
E-Paper 5-6 2010

Öffentliche APIs

Die Cloud braucht API

Heutzutage lassen sich Clouddienste wie Salesforce oder AWS (Amazon Web Services) nicht mehr wegdenken. Firmen sind daran interessiert diese Angebote 24h am Tag zu nutzen. Die Anwendung beschränkt sich dabei nicht nur auf die Möglichkeiten via Browser; es gibt auch APIs die von diesen Diensten angeboten werden. Die Verwendung dieser APIs ermöglicht es einem Nutzer die angebotenen Dienste sehr flexibel, auf seine Bedürfnisse angepasst, zu nutzen. Außerdem lassen sich Angebote verschiedener Clouddienste durch die Verwendung deren APIs sehr gut integrieren.

ine steigende Anzahl Unternehmen öffnet ihre Web Applikationen für Partner und mobile Endgeräte. Ein steigendes Interesse für E-Commerce, iPads und Smartphones hat diesen Trend bereits 2011 begründet und es ist zu erwarten, dass er 2012 noch an Fahrt gewinnt. Hierfür werden öffentliche APIs eingerichtet, sodass externe Webseiten und mobile Apps auf bestimmte Funktionen und Daten zugreifen können.

Scott Morrison, CTO bei Layer7 und Experte auf dem Gebiet Cloud und SaaS, gibt im Folgendem grundlegende Tipps für Firmen, die den Schritt wagen wollen, eine API zur Verfügung zu stellen und externe Entwickler einzuladen, sich ihrer Applikationen zu bedienen. Bereits im Vorfeld sollte folgendes beachtet werden:

1) Welche Ziele verfolgt das Unternehmen mit der Bereitstellung der API?

Im Vorfeld ist es ratsam, Nutzen und Risiken abzuwägen: Lohnt sich die Exposition der Daten?

Welche Stelle ist für das Projekt verantwortlich? IT- oder Marketingabteilung, Website Manager?

2) Wichtige Werkzeuge zur Bereitstellung einer API

API-Proxy: Es ist wichtig einen Gateway zu haben, der reguliert, wer Zugang zu welcher Programmierschnittstelle hat. Über den Gateway werden Sicherheitsrichtlinien, SLA Controls und Daten-Mapping festgelegt.

Developer Portal: Die Einrichtung eines zentralen Anlaufpunkts für die Kommunikation mit den Entwicklern ist empfehlenswert. Dies ermöglicht es Entwicklern, Informationen und Tipps einzuholen und ihre Projekte zu planen.

3) Entwickler für die Nutzung der API gewinnen

Wettbewerb für die beste App ausrufen

Ein Developer Camp ausrichten

Bewerben innovativer Apps die auf die API aufbauen

Werbung auf einschlägigen Webseiten für Developers schalten

Programmieren bei der Monetarisierung ihrer Apps unterstützen

4) Freier oder kostenpflichtiger Zugang zur API?

Beides ist anzuraten. Bieten Sie eine Gratisversion sowie eine kostenpflichtige Premiumversion an. Letztere kann beispielsweise erweiterte Funktionalität und Support umfassen.

5) Gängige Fehler bei der Bereitstellung einer API vermeiden

Benutzen Sie einen robusten Proxi, der eine Vielzahl von Sicherheits- und Managementkontrollen bietet.

Am Anfang kleine Schritte wagen: Konzentrieren Sie sich darauf, eine API bereitzustellen und ziehen sie Ihre Lehren aus den ersten Kinderkrankheiten. Erst wenn die Anfangsfehler ausgemerzt worden sind, sollte die oben beschriebenen Ziele, wie beispielsweise die Umsatzsteigerung, angegangen werden.

Manche Firmen stellen ihre APIs ohne IT-Support zur Verfügung. Sollte ein gravierender Fehler auftreten, der nicht umgehend behoben werden kann, kann dies das Ende des Projekts bedeuten und sich auch auf zukünftige Initiativen auswirken.

OAuth, so geht’s

Viele Dienstanbieter verwenden das OAuth-Protokoll zur Authorisierung für den Zugriff auf ihre APIs. Konkret soll einer dritten Partei der Zugriff auf Ressourcen eines Benutzers gewährt werden, ohne jedoch die Benutzerdaten dieser dritten Partei preiszugeben.

Dieser Artikel soll explizit zeigen, wie OAuth in Applikationen genutzt werden kann. Um dies zu tun wird im Speziellen auf die Version 1.0a eingegangen, die sehr verbreitet ist.

Die größte Schwierigkeit für einen Applikationsentwickler und Nutzer angebotener APIs, deren Zugriff durch OAuth authorisiert wird, ist die meist schlechte Möglichkeit den Grund für Fehlermeldungen zu erfahren. OAuth 1.0a beschreibt zwar sehr genau, wie und wann OAuth Parameter eingesetzt werden müssen. Werden dabei aber Fehler gemacht, wird vom API Anbieter häufig nur eine sehr allgemeine und wenig aussagekräftige Fehlermeldung als Antwort geliefert. Die größte Fehlerquelle liegt in der Berechnung der Signatur, die explizit gefordert wird. OAuth Parameter werden benötgt, wenn ein Request Token angefordert wird, wenn ein authorisierter Request Token für einen Access Token eingetauscht wird und bei jedem Aufruf einer API. Um Hilfestellung zu liefern, werden nun die Parameter anhand eines kurzen Beispiels im Einzelnen erläutert:

Für den Aufruf einer API werden folgende Informationen und Werte benötigt:

1.       oauth_consumer_key und oauth_consumer_key_secret
Diese müssen beim Dienstanbieter abgeholt werden. Dies geschieht bei der Registrierung der Applikation, welche entwickelt werden soll. Der oauth_consumer_key wird auch als API Key bezeichnet. In diesem Beispiel lauten API Key/ API Key Secret: myApiKey/ myAPiKeySecret. In der Regel sind dies base64 encoded Zeichenketten

2.       drei URL Endpunkte des API Anbieters müssen bekannt sein (Beispiele):

a.       Request Token Endpunkt
(https://services.dienstanbieter.com/auth/oauth/request)

b.      Autorisierungs Endpunkt
(https://services.dienstanbieter.com/auth/oauth/authorize)

c.       Acces Token Endpunkt
(https://services.dienstanbieter.com/auth/oauth/token)

3.       Für jeden Endpunkt muss herausgefunden werden, welche HTTP Methode verwendet werden muss. Diese werden nur Teilweise in der Spezifikation fest vorgeschrieben

4.       Zur Berechnung der Signatur muss herausgefunden werden, welche Typen von Signatur unterstützt werden (HMAC‑SHA1, RSA‑SHA1, PLAINTEXT)

OAuth dance

Das Protokoll sieht in etwas so aus:

1.       Registrieren einer Applikation beim Dienstanbieter

2.       Einen Request Token beim Dienstanbieter anfordern

3.       Den emfpangenen Request Token vom Benutzer authorisieren lassen

4.       Den authorisierten Request Token gegen einen Access Token eintauschen

5.       APIs mit dem empfangenen Access Token aufrufen

Detaildarstellung (nur der initiale Request wird in jedem Detail dargestellt):

1.       Request Token anfordern

a.       POST https://services.dienstanbieter.com/auth/oauth/request

b.      HTTP Header, alles auf einer Zeile, durch Komma (,) getrennt:

                       i.   Authorization: OAuth,

1.       Zwingend gefordert, optional kann das Attribut „realm“ hinzugefügt werden (OAuth realm=“http://www.dienstanbieter.de“, ...)
WICHTIG: das Attribut realm darf bei der Berechnung der Signatur nicht berücksichtigt werden!

                     ii.   oauth_consumer_key=”myApiKey”,

                    iii.   oauth_signature_method=”HMAC‑SHA1”,

1.       der verwendete Signatur‑Typ

                     iv.   oauth_signature=”bmi9wrrN5GYp7Ddxy1hrXONLW88%3D”,

1.       bei der Verwendung des Typs HMAC‑SHA1 werden alle Werte des Aufrufes in die Berechnung der Signatur mit einbezogen
(ausser „realm“ und „oauth_signature“)

2.       der sogenannte SignatureBaseString lautet so:

a. POST&https%3A%2F%2Fservices.dienstanbieter.com%2Fauth%2Foauth%2Frequest&oauth_callback%3Dhttps%253A%252F%252Fmyhost%253A8443%252FConsumerApp%253Fstate%253Dauthorized%26oauth_consumer_key%3DmyApiKey%26oauth_nonce%3D1712310%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1323106353%26oauth_version%3D1.0

3.       das genutzte gemeinsame Geheimnis (shared secret):

a.       myApiKeySecret&
ACHTUNG: bei jeder Berechnung müssen das API Key Secret und das aktuelle Token Secret durch ein ‚&‘ kombiniert werden. Da beim initialen Aufruf kein Token Secret existiert, bleibt der Wert hinter ‚&‘ leer

                       v.   oauth_timestamp=”1323106353”,

1.       ein UNIX timestamp

                     vi.   oauth_nonce=”1712310”,

1.       ein beliebiger, sich nicht wiederholdender Wert

                    vii.   oauth_version=”1.0”,

1.       dieser Wert ist optional. Wird er verwendet, muss er den Wert „1.0“ enthalten, obwohl hier OAuth 1.0a verwendet wird

                  viii.   oauth_callback=” https%3A%2F%2Fmyhost%3A8443%2FConsumerApp%3Fstate%3Dauthorized”

1.       eine gültige URL oder „oob“ falls es keine URL gibt. Diese URL wird vom Server aufgerufen, nachdem ein Benutzer im späteren Verlauf den Request Token authorisiert hat

2.       Antwort des Dienstanbieters, als Text im HTTP body (alles auf einer Zeile):

a. oauth_token=000001333cbded1e-4a1&

                                                               i.      der Request Token. Dieser wird im späteren Verlauf durch den Benutzer authorisiert. ‚&‘ dient der Konkatenation mit weiteren Werten

b.      oauth_token_secret=10262011205050062&

                                                               i.      das gemeinsame Geheimnis (shared secret). Dieses wird für die Berechnung der Signatur benötigt, nachdem der Request Token authorisiert und gegen einen Access Token eingetauscht wird. ‚&‘ dient der Konkatenation mit weiteren Werten

c.       oauth_callback_confirmed=true

Acces Token

Der Client tauscht den authorisierten Request Token gegen einen Acces Token ein indem er einen Aufruf an den Acces Token Endpunkt des Dienstanbieters richtet. Dabei enthält der Aufruf wieder den HTTP Header „Authorization“. Diesmal mit diesen Parametern:

1.       Authorization: OAuth,

2.       oauth_consumer_key=“...“,

3.       oauth_token=“000001333cbded1e-4a1“,

a.       der authorisierte Request token

4.       oauth_signature_method=“...“,

5.       oauth_signature=“...“,

a.       für die Signatur wurde das gemeinsame Geheimnis (shared secret) verwendet, welches mit dem Request Token empfangen wurde (10262011205050062)

6.       oauth_timestamp=“...“,

7.       oauth_nonce=“...“,

8.       oauth_version=“...“,

9.       oauth_verifier=“abcdefgh123456“

a.       der Verifier, der mit dem authorisierten Request Token empfangen wurde

Die Antwort enhält zwei Parameter im HTTP body Element: oauth_token und oauth_token_secret:

oauth_token=d8d8d84j4j445454&oauth_token_secret=dfhdf74584u545jkj

oauth_token ist der Access Token. Dieser Token hat eine zeitlich unbestimmte Lebendauer, falls dies nicht anders von Dienstanbieter dokumentiert wurde. Die Spezifikation schreibt nicht konkret vor, dass es eine Begrenzung geben muss.

API Aufruf

Jetzt, wo der Access Token beim Client vorhanden ist, muss dieser mit jedem API Aufruf verwendet werden. Zudem muss jeder API Aufruf mit dem gemeinsamen Geheimnis (shared secret) signiert werden. Jeder Aufruf muss folgende Parameter im HTTP Header „Authorization“ enthalten:

1.       Authorization: OAuth,

2.       oauth_consumer_key=“...“,

3.       oauth_token=“d8d8d84j4j445454“,

a.       der Access Token

4.       oauth_signature_method=“...“,

5.       oauth_signature=“...“,

a.       für die Signatur wurde das gemeinsame Geheimnis (shared secret) verwendet, welches mit dem Access Token empfangen wurde (dfhdf74584u545jkj)

6.       oauth_timestamp=“...“,

7.       oauth_nonce=“...“,

oauth_version=“...“

Der Dienstanbieter wird den gewünschten Inhalt liefern.

Gut zu wissen

Sämtliche Parameter Namen und Werte müssen percent encoded werden. Ein häufiger Fehler ist es die Werte zur Berechnung der Signatur nicht nocheinmal zu encoden. Der Vorgang muss prinzipiell so durchgeführt werden:

1.       jeden Parameter Namen %‑encoding

2.       jeden Parameter Wert %‑encoding

3.       die Parameter und Werte nach Parameter Namen sortieren, dann nach Wert und mit einem ‚&‘ konkatenieren

4.       den SignatureBaseString erstellen

a.       ‚HTTP Methode‘&‘requestURL‘&‘requestURLQuery‘&‘oauthParameter

b.      WICHTIG: hier alle Werte %‑encoden! Es wird auch von double‑encoding gesprochen

Der generierte SignatureBaseString dient als Eingabewert für die Berechnung der Signatur vom Typ HMAC‑SHA1.

Für die Entwicklung einer Applikation, die OAuth verwendet, sollten unbedingt vorhandene Testwerkzeuge verwendet werden.

Dienste anbieten

Ist es das Ziel, eigene APIs anzubieten und die entsprechenden Aufrufe durch OAuth authorisieren zu lassen, sollte unbedingt auf Produkte zurückgegriffen werden, die dies ermöglichen. Eine gewählte Lösung sollte dabei sehr flexbiel und damit anpassbar sein. Die OAuth Spezifikation lässt es zu, anbieterspezifische Parameter bei Aufrufen zuzulassen. Dies sollte sich mit wenig Aufwand realisieren lassen.

Hat ein Unternehmen vor einen Dienst anzubieten, müssen unbedingt Fragen zur Verwaltung von Token gestellt werden. Soll es eine Lebendauer geben, sollen Token wiederverwendet werden, sollen API Keys für alle oder nur einen Teil der angebotenen APIs gültig sein, wer darf wieviele Aufrufe einer API durchführen?

Zudem müssen APIs vor jeder Art unberechtigten Zugriffes geschützt werden. Benutzer müssen sich zunächst authentifizieren, bevor sie einer Applikation den Zugriff gestatten. Welche Art Fehlermeldung soll zurückgeliefert werden. Soll es für Entwickler eine Art debugging Konsole geben um die Entwicklung zu vereinfachen?

Dimitri Sirota

__________________________________________

Dimitri Sirota, Vice President Marketing & Alliances

Layer 7 Technologies (http://www.layer7tech.com/).