AWS-Amplify ist eine neue Javascript Library von Amazon Web Services (AWS), die eine einfache AWS Cloud Service Integration in React, React-Native und Angular bereitstellt. Nachfolgend wird der Authentifizierungsmechanismus von Amazon Cognito erklärt, damit nur berechtigten Personen den Zugriff auf den App-Inhalt und den S3 Speicher erhalten. Danach wird die Integration des Amplify-Hubs und seine Rolle in einer React App beschrieben. Für das Tutorial wird AWS-Amplify (Module) und AWS-Amplify-React (Auth-Form) benötigt.
npm install aws-amplify
Authentifizierung:
Die Grundvoraussetzung der Authentifizierung ist ein Cognito User-Pool mit einem App-Client ohne Secret Key, da zum jetzigen Zeitpunkt (04.05.2018) der Secret Key nicht mit dem Amplify-Cognito Modul funktioniert.
Als nächstes muss das Modul konfiguriert werden. Das sollte so früh wie möglich in der App.tsx oder, je nach Stuktur des Projekts, sogar noch früher geschehen.
import Amplify from 'aws-amplify'; Amplify.configure({ Auth: { // REQUIRED - Amazon Cognito Identity Pool ID identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', // REQUIRED - Amazon Cognito Region region: 'XX-XXXX-X', // OPTIONAL - Amazon Cognito User Pool IDuserPoolId: 'XX-XXXX-X_abcd1234', // OPTIONAL - Amazon Cognito Web Client ID (26-char alphanumeric string) userPoolWebClientId: 'a1b2c3d4e5f6g7h8i9j0k1l2m3', // OPTIONAL - Enforce user authentication prior to accessing AWS resources or not mandatorySignIn: false, }
Die Amazon Cognito Identity Pool ID findet man ein wenig versteckt in der AWS-Console unter Cognito:
Manage Federated Identities -> Name des Identity Pools:
Dann auf Edit identity Pool:
Die Region steckt steht am Anfang der Identity Pool ID und geht bis zum Punkt:
Die User Pool ID befindet sich auf dem UserPool Dashboard unter General Settings :
Auch die Web Client ID findet man im Dashboard unter App Clients -> App Client ID :
Das Einbinden der Anmeldemaske in React (React Auth Form) und die nur mit Authentifizierung zu erreichenden Inhalte werden über eine High-Order-Component (HOC) und die Funktion withAuthenticator() eingebunden. Eine HOC ist eine Funktion die als Argument ein Component empfängt und ein neues Component zurück gibt. Dieses Prinzip kennt man aus funktionalen Programmiersprachen wie Scala und den Higher Ordered Function, die eine Tranformation von Datentypen ermöglichen (z.B. map oder flatMap). Die Funktion withAuthenticator() sorgt dafür, dass der Nutzer eine Anmeldemaske sieht, wenn er nicht angemeldet ist. Das Anmeldefenster wird bei einem Sign-In oder Sign-Up Vorgang ausgeblendet und es wird eine Event Nachricht an den Amplify-HUB gesendet.
import { withAuthenticator } from 'aws-amplify-react'; export default withAuthenticator(App);
Ab diesem Zeitpunkt kann die App nur noch mit einem gültigen Login verwendet werden. Das Modul bietet die Möglichkeit eigene Komponenten an die withAuthenticator() Funktion zu übergeben, damit das Aussehen und die Funktionalität angepasst werden kann. Die Meldungen zu den Vorgängen im Authenticator werden über den Amplify-HUB gesendet.
HUB:
Der Amplify-HUB ist ein Nachrichten Bus, der in der App zur Kommunikation zwischen einzelner Komponenten verwendet werden kann. Über den ‘auth’ Kanal des Hubs werden auch alle Authenticator Meldungen gesendet.
Die Konfiguration eines HUB’s Listeners erfolgt im Constructor der jeweiligen React-Komponente. Mit der Funktion “onHubCapsule” kann die Verbindung zwischen dem Channel und einer Funktion zur Verarbeitung der Nachrichten hergestellt werden. Hier am Beispiel des ‘auth’ Channels.
import { Hub } from 'aws-amplify'; constructor() { Hub.listen('auth', this, 'AuthListener'); } onHubCapsule(capsule) { const { channel, payload } = capsule; if (channel === 'auth') { onAuthEvent(payload); } } onAuthEvent(payload) { const { event, data } = payload; switch (event) { case 'signIn': break; case 'signUp': break; case 'signOut': break; case 'signIn_failure': break; } }
Ebenso können auch Nachrichten über die spezifizierten Channels gesendet werden. Diese können dann in allen Components empfangen werden, die einen Listener im Constructor auf den spezifischen Channel besitzen. Das Senden der Nachrichten kann in jeder Komponente wie folgt vorgenommen werden:
import { Hub } from 'aws-amplify'; Hub.dispatch('auth', { event: 'signIn', data: user }, 'Auth');
Storage:
Das Amplify-Storage Modul erleichtert das Einbinden von Objekten (Assets) aus dem AWS S3 Speicher und kann auch zum Upload von Daten der User in öffentliche oder private Ordner auf dem angegeben S3 Bucket verwendet werden.
Vor der Verwendung muss auch der S3-Storage konfiguriert werden.
import Amplify from 'aws-amplify'; Amplify.configure({ Storage: { //REQUIRED - Amazon S3 bucket bucket: '', //OPTIONAL - Amazon service region region: 'XX-XXXX-X', //Specify your identityPoolId for Auth and Unauth access to your bucket; identityPoolId:'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab' } });
Als “Bucket” Variable muss der Name des S3-Buckets von AWS eingegeben werden. Dieser kann in der AWS-Console unter S3 abgerufen werden. Der Name darf nicht mit der kompletten Bucket ARN verwechselt werden, die jedoch am Ende ebenso den Namen des Buckets enthält. Die Region des Buckets wird nicht benötigt, kann aber zur Verbesserung der Latenz angegeben werden. Die Identity Pool ID wird benötigt sollte man mit der API von S3 Arbeiten wollen. Dafür benötigt man aber auch berechtigte Cognito Benutzer.
Zur Benutzung von öffentlich freigegebenen Objekten (Assets) aus dem Bucket kann das Amplify-React image Tag verwendet werden. Der imgKey spezifiziert dabei das Objekt (Bild) aus dem S3-Bucket.
import { S3Image } from 'aws-amplify-react'; render() { return lt;S3Image hidden imgKey={key}/gt; }
Darüber hinaus bietet die AWS Amplify Library noch einige weitere nützliche Module für moderne Cloud-Applikationen:
- Cache
- Analytics
- API
- PubSub
- PushNotifications
- I18n
- Logger
Diese können für verschiedene spezifische Einsatzbereiche wie API Calls über REST- oder GraphQL- Schnittstellen, AWS-Analytics, App-Cache und Push Notifications mit Kampangen Analysen und Targeting, Internationalisierung und Logging verwendet werden.