• Dennis Hills

    How to Store Your App Photos in the Cloud Using Amazon S3 [tutorial and code samples]

    About

    Welcome to the first installment of our blog series showing how to build some of the most popular end-to-end experiences used by mobile apps. In each installment, you’ll see how you can build these experiences – including the client (iOS and Android) and the backend (AWS services) – in just a few minutes. We’ll typically use AWS Mobile Hub to accomplish this; Mobile Hub simplifies many of the steps you would normally have to go through, including authenticating users, securely configuring backend services, running backend code, and generating reference iOS and Android apps that use these features. We’ll then dive deeper, showing you how to integrate the experiences into your own applications and explaining what is happening within Mobile Hub. Through the series, we’ll touch on a number of AWS services, including Amazon Cognito, Amazon S3, Amazon DynamoDB, and AWS Lambda. We welcome your suggestions in the comments for additional experiences or AWS services we should highlight!

    Let’s get started with our first installment. This first post is about uploading photos to and downloading photos from the cloud from a mobile application. You’ll walk away with a fully functioning mobile application connecting to your AWS backend resources.

    There are three steps in this tutorial.

    Step 1. Configure the backend AWS resources via AWS Mobile Hub. This consists of creating a project, enabling a single feature called User Data Storage, and building/downloading the iOS Swift sample app source code project.

    Step 2. Explore uploading to and downloading photos from Amazon S3 using the sample app generated by Mobile Hub.

    Step 3. Store and Retrieve Photos from your own app by following the AWS Mobile Hub integration guide customized for your project.

    First, we’ll explain briefly what Mobile Hub is and the AWS features (Amazon S3 and Amazon Cognito Identity) that we’ll enable within a Mobile Hub project.

    What is AWS Mobile Hub

    AWS Mobile Hub simplifies the process of building, testing, and monitoring mobile applications that make use of one or more AWS services. It can help you skip the front- and back-end heavy lifting of manually creating cloud service configurations and integrating them into your client.  The mobile app features supported includes user authentication, data storage, backend logic, push notifications, content delivery, and analytics—all from a single, integrated console.

    There is no charge for Mobile Hub; you only pay for the AWS services used. For example, after you complete this tutorial, you are only charged for the objects stored in your S3 bucket. Learn more about AWS Mobile Hub features.

    What is Amazon Cognito Federated Identity

    Amazon Cognito Federated Identities enable you to create unique identities for your users and authenticate them with identity providers. With an identity, you can obtain temporary, limited-privilege AWS credentials to synchronize data with Amazon Cognito Sync, or directly access other AWS services. Amazon Cognito Identity supports public identity providers—Amazon, Facebook, Google, and SAML identity providers—as well as unauthenticated identities, which is what we’ll be utilizing in this tutorial. Learn more about Amazon Cognito Federated Identities.

    What is Amazon S3

    Amazon Simple Storage Service (Amazon S3) provides secure, durable, highly scalable object storage in the cloud. Using the AWS Mobile SDK, you can directly access Amazon S3 from your mobile app. The AWS Mobile SDK allows you to consume the Amazon S3 service in your mobile application via the S3 Transfer Utility. The fully functional iOS sample app generated by Mobile Hub includes the AWS Mobile SDK for iOS, S3 Transfer Utility, and all the helper code for running the demo app used for this tutorial. Learn more about Amazon S3 cloud storage and pricing.

    Let’s Begin

    Step 1 - Configure the backend

    We’ll use Mobile Hub to create a project and then enable the User Data Storage feature to store and retrieve photos from Amazon S3. We walk you through the steps and follow up with a recap (explain the magic) of what just happened.
     

    1)  Launch AWS Mobile Hub console

    2)  Select Create new mobile project.

    3)  Provide a project name, S3Blog, and then select Create project.
    Note: If you have never used Mobile Hub before, you’ll be prompted to select Get Started and Yes, grant permissions before you can create a new project.

    4)  Select User Data Storage.
     

    5)  Select Store user data and then choose Save changes.
     

    6)  Select Integrate from the left panel
     
     

    7)  From the integration tab, make sure iOS Swift is selected and that you are in the Getting Started section.
    8)  Select Download a sample app to download your iOS Swift project source code (zipped project folder). We’ll run this project in Xcode in just a minute.
     
    Done. You now have all your AWS resources configured and the custom-built iOS Swift source code project is downloaded and ready.
     

    What did we just do?

    First, we created a new project in AWS Mobile Hub. Note that, for each Mobile Hub project created, an Amazon Cognito identity pool is created on your behalf, regardless of what features are enabled. Amazon Cognito Identity is being used in our app to obtain temporary, unauthenticated, limited-privilege credentials to directly access Amazon S3 from a mobile app.

    In a future blogpost, we’ll discuss the Mobile Hub User Sign-in feature where Amazon Cognito provides authenticated identities through Amazon Cognito User Pools and public identity providers—Amazon, Facebook, Google, and SAML. for this tutorial, just know that we’ll be using Amazon Cognito unauthenticated identities to demonstrate this topic.

    After the project was created with the default Amazon Cognito identity pool, you then enabled the User Data Storage feature in your Mobile Hub project. This feature first creates an Amazon S3 bucket to store user photos and creates a policy within the AWS Identity and Access Management (IAM) role that grants your user’s access to Amazon S3 when they launch the app. Within the S3 bucket, a /Public folder was created with access permissions set to allow all users of your app to view and upload files stored there. There’s also a /Private folder created, which we’ll discuss in the next blog post. This folder is used to store private data for each user when authenticated through the User Sign-in feature of Mobile Hub.

    Here’s how the sample app works: The user launches the app and immediately that user is given a unique unauthenticated Amazon Cognito Identity. The user then selects the User Data Storage demo feature to upload a photo from his or her photo library to the /Public folder within the S3 bucket. The unique unauthenticated Amazon Cognito Identity given to that user provides limited-privilege credentials to directly access the /Public folder of your S3 bucket.

    Now that we have created file storage that is designed for scalability, let's go demo the app!

    Step 2 - Running the Sample APP

    Now for the fun part. In the previous step 1, you configured the AWS resources you needed, built the sample app project code, and downloaded it to your Mac. At the end of this walkthrough, we’ll go into how Mobile Hub guides you in integrating these features into your own app.

    For now, we’ll now describe how to open the sample project code in Xcode and run the iOS sample app on a physical iOS device or simulator. It’s that simple.

    The iOS sample app provides a demo for retrieving files from your S3 bucket and uploading photos from your iOS device photo library. Mobile Hub has placed a sample image to get started.

    1) Unzip the iOS Swift project code you downloaded previously

    2) Open the sample app project in Xcode by double-clicking on the Xcode project, MySampleApp.xcodeproj, which is in the project folder.

    3) Select build/run within Xcode to build and run the sample app.

    When the sample app is first launched, a function called is called to retrieve an ID generated by the Amazon Cognito Identity service. The function invokes that manages access to Amazon Cognito. The following method illustrates how to retrieve an app user's identity

    4) At the main screen of the sample app, select User Data Storage and then Demo User File Storage feature.

          

    You are now in the User File Storage demo and you’ll see example-image.png, which Mobile Hub provided to get started. You can now download the example image from Amazon S3 to your device.

    5) To download an image from the list, select the file and then choose Download from the action item list as shown.

    Here’s the sample function that is used to download files from Amazon S3 to the mobile app.

    You should now see a green check mark next to the example image, which indicates that it has been downloaded from Amazon S3 and cached locally in the app.

    Now you can upload an image to Amazon S3 from your camera roll.

    6) To upload a photo from your photo library to Amazon S3, select the action icon on the upper right of the screen and then choose Upload from within the User File Storage demo of the sample app.

    7) The app will request access to your photo library. Select OK.

    8) Now the app has access to your camera roll and you can select a photo to upload to Amazon S3. Here, you can select a waterfall image.

    9) After you select an image, you are prompted to give your file a name. Give it a name and make sure you add .png to the end as shown so the app can recognize this as an image. Select Done and you’ll see the activity indicating the image is being uploaded to Amazon S3.

             

    After the image upload completes, it’ll show in the list but without the green check mark, which indicates it’s now in the cloud (stored in your S3 bucket) but not cached locally in the app.

    Here’s the sample iOS Swift function code used for uploading images from your app to Amazon S3.

    What did we just do?

    We just provisioned AWS backend resources consisting of an Amazon Cognito ID and Amazon S3 bucket using AWS Mobile Hub. We then built and launched the generated sample app. The app demonstrates the User Data Storage feature by uploading photos from your iOS device to Amazon S3 and downloading photos from Amazon S3 to your iOS device.

    Are you done playing? We hope you enjoyed this tutorial. Stay tuned for the next installment where we’ll build on this idea and add user sign-in for more private storage and user data sync.

    Are you interested in looking behind the curtain? To see that image you uploaded in the S3 bucket that was created for you, choose the Resources button on the left-hand navigation of the Mobile Hub console, choose the link in the tile labeled Amazon S3 buckets to open the Amazon S3 console, then choose the Public folder.

    Planning to integrate this feature into your own app? No problem! In step 3, next, we’ll walk you through the Mobile Hub integration guide, helping you integrate all the code from the sample app into your own app.

    Step 3 - Store and retrieve photos from your own app

    You just configured a backend file storage and ran our generated sample app to demonstrate the end-to-end functionality of this common mobile feature. However, what you really need is the same functionality in your own app. Mobile Hub provides integration instructions specific to each mobile project you create. Let’s get started.

    Go back to your Mobile Hub project in the console and select Integrate. The integration instructions from Mobile Hub will first walk you through Getting Started and then describe each feature you enabled in your Mobile Hub project and how to integrate each of them into your own app.

    Here’s a quick overview of Getting Started and additional instructions for integrating this project into your own application.

    The Mobile Hub Getting Started integration instructions include:

    Download the Mobile SDK for iOS and custom source code provided

    • The download provides the latest SDK, Mobile Hub helper code, and example source code to get you started. 
    • After downloading the SDK and helper code, drag and drop the Sdk folder contained in the download into your own project within Xcode. This assumes you already have an iOS Swift project of your own; if not, create a new one and follow along.
    • Add the AWS SDKs as Embed Frameworks.
    • Add Run Script phase to your project as directed.
    • Copy the AmazonAws folder from the helper code to your project and add a group for it. This source code contains a customized helper framework that simplifies the use of all the SDKs that are required to support your project.It also contains the AWSMobileClient.swift file, which bootstraps the app and creates an identity manager to establish the user identity with Amazon Cognito.
    • Copy the AWS dictionary from the integration Info.plist into your own project Info.plist. The AWS dictionary provides the CognitoIdentity poolId and region for your project.
    • Add AWS iOS SDK dependencies, libsqlite3.tbd and libz.tbd, under Linked Frameworks and Libraries as directed.
    • Set up your Application Delegate by returning the AWSMobileClient singleton as shown:

    You are now done with the Getting Started section.

    After you complete Getting Started, you can then select User Data Storage in the left panel of the integration instructions. Here, you just need to do the following:

    • Copy the AWS dictionary from the integration Info.plist into your own project Info.plist. The AWS dictionary already provides all the CognitoIdentity pool IDs for your project as well as the S3 bucket and region.
    • View or copy the example upload/download source code provided. The idea is to use this code in your own UIViewController.

    That’s it! You should now be able to run your own application and connect it to your AWS resources like we demonstrated using the sample app generated by AWS Mobile Hub.

    Conclusion

    We just configured a backend data storage feature via AWS Mobile Hub, generated a fully functional sample iOS app demonstrating uploading and downloading photos to and from S3, and then walked through integrating the client code into your own app, connecting to the same backend resources demonstrated in the sample app.

    Thanks and happy coding!

  • Marc Teichtahl

    Using webpack with the Amazon Cognito Identity SDK for JavaScript

    This blog post is aimed at developers of all experience levels who develop and deploy JavaScript based applications (whether server-side with Node.js or client side) that incorporate the AWS SDK, the Amazon Cognito Identity SDK for JavaScript and who also use the popular webpack module bundler.

    In July 2016, Amazon Web Services launched Amazon Cognito User Pools, a feature that makes it easy for developers to add sign-up and sign-in functionality to mobile and web applications. To help developers easily realize the power of user pools within their own applications, we also released the Amazon Cognito Identity SDK for JavaScript.

    Amazon Cognito User Pools allows you to easily add user sign-up and sign-in to your mobile and web applications. The fully managed user pool can scale to hundreds of millions of users and you can have multiple directories per AWS account. Creating a user pool takes just a few minutes and allows you to decide exactly which attributes (including address, email, phone number as well as custom attributes) are mandatory and even optional when a new user signs up for your application or service. Your application can also specify the desired password strength, whether the use of Multi-Factor Authentication (MFA) is required, and verify new users via phone number or email address to further enhance the security of your application.

    If you are new to the Amazon Cognito Identity SDK for JavaScript this AWS blog post is a great place to start.

    Why Use Asset & Module Bundling with the Amazon Cognito Identity SDK for JavaScript

    Today, modern web applications for both mobile and desktop have to provide the user with a secure, fast, responsive, and native-app-like experience. There is no doubt that modern browsers are extremely powerful and cater to a vast array of possible implementation approaches. Many of the more popular implementations rely heavily on the deployment of a JavaScript application through some form of asset packaging and/or module bundling. This allows a developer to take their JavaScript application and create one or more files that can be loaded by the client browser by using script tags.

    There are many schools of thought on how you can achieve this packaging , including task runners such as Grunt and Gulp, and bundlers such as Browserify. However, there is a general consensus that asset packaging is not only about improving load times—it enables the modularization of your application while ensuring testability and robustness.

    Using webpack with the Amazon Cognito Identity SDK for JavaScript

    In the many requests we get to provide more detail on how to integrate the Amazon Cognito Identity SDK for JavaScript within a webpack environment, we’re specifically asked how to ensure that webpack correctly manages the following third-party dependencies:

    Throughout these examples, the following bower libraries are used by bower.json

    "aws-cognito-sdk": "https://raw.githubusercontent.com/aws/amazon-cognito-identity-js/master/dist/aws-cognito-sdk.js",
"amazon-cognito-identity": "https://raw.githubusercontent.com/aws/amazon-cognito-identity-js/master/dist/amazon-cognito-identity.min.js",
"sjcl": "https://raw.githubusercontent.com/bitwiseshiftleft/sjcl/master/sjcl.js",
"jsbn": "https://raw.githubusercontent.com/andyperlitch/jsbn/master/index.js",

    For all the reasons we gave earlier for the importance of asset packaging to development processes, and unless your application is extremely small, the use of an asset packaging tool such as webpack is almost always recommended. Of course, one could simply pull in all of these dependencies using tags. However, this would pollute global namespace, and not provide the most optimal resource management and loading approach. Many developers start with a standard webpack.config.js file that has a standard babel loader, as shown here.

    {
  /** test for file ending in js or jsx 
   * exclude node_module and bower_components - we dont want to babel these 
   * use the babel loader 
   * apply the react and es2015 (es6) transformations **/

  test: /\.jsx?$/,
  exclude: /(node_modules|bower_components)/,
  loader: 'babel',
  query: {
    presets: ['react', 'es2015']
  }
}

    It’s important to remember that this configuration doesn’t take into account that some of third-party dependencies used by the Amazon Cognito Identity SDK for JavaScript currently do not use the Universal Module Definition (UMD) pattern for JavaScript.

    The UMD pattern attempts to offer Asynchronous Module Definition (AMD) based compatibility with the most popular script loaders of the day such as RequireJS and CommonJS.

    This is a pattern that webpack relies on, and so we must make some changes to how webpack loads these modules. Without these changes, you may encounter errors such as the following.

    amazon-cognito-identity.min.js:19 Uncaught ReferenceError: BigInteger is not defined

    Such an error may be encountered when making a call to AWSCognito.CognitoIdentityServiceProvider.CognitoUser property authenticateUser This is an example of where we can make use of the webpack imports and exports loader capability to overcome this error.

    Using webpack Loaders

    According to the webpack documentation "loaders allow you to preprocess files as you require() or “load” them. Loaders are kind of like “tasks” are in other build tools, and provide a powerful way to handle front-end build steps. Loaders can transform files from a different language like, CoffeeScript to JavaScript, or inline images as data URLs"

    In order to resolve the lack of UMD compatibility, you will rely to two specific loaders, import and export.

    Using the Export Loader

    In the case of the Amazon Cognito Identity SDK for JavaScript, we need to ensure we export theAWSCognito variables into the scope of the module that requires/imports (for ES6) them.

    {
  test: /aws-cognito-sdk\/index\.js/,
  loader: 'exports?AWSCognito'
}

    Using the exports loader has the effect of exporting a module method within bundle created by webpack. As a result, both AWSCognito and AWS are now accessible when required or import(ed) (for ES6).

    var AWSCognito = require('aws-cognito-sdk')

/*** EXPORTS from export-loader ***/ 
module.exports = AWSCongito

    More information about the exports loader can be found here

    Using the Import Loader

    The import loader is mostly used to inject (import) variables into the scope of another module. This is especially useful if third-party modules are relying on global variables like BitInteger or sjcl as is the case with Amazon Cognito Identity SDK for JavaScript.

    If you don’t use the webpack loader, the following is generated within the bundle.

    __webpack_require__(431);       // refers to jsbin
__webpack_require__(432);       // refers to sjcl

    Beacuse neither jsbin or sjcl export anything, any calls that rely on these modules will result in an error.

    To resolve this, we can use the following webpack loader configuration:

    {
  test: /amazon-cognito-identity\/index\.js/,
  loader: 'imports?jsbn,BigInteger=>jsbn.BigInteger,sjcl'
},
{
  test: /sjcl\/index\.js/,
  loader: 'imports?sjcl'
}

    This injects the following into the bundle (in this case bundle.js) created by webpack.

    
/*** IMPORTS FROM imports-loader ***/
var jsbn = __webpack_require__(431);
var BigInteger = jsbn.BigInteger;
var sjcl = __webpack_require__(432);

    As a result, jsbn, BigInteger and sjcl are all imported from their respective modules into Amazon Cognito Identity SDK for JavaScript.

    More information about the import loader can be found here

    Next Steps

    We encourage you to download the Amazon Cognito Identity SDK for JavaScript and start building your application. Coupled with webpack, and by following the guidance in this blog, you we hope you have a smooth development experience.

    If you have any comments or questions, please free to comment below, reach out via email (teichtah@amazon.com) or raise an issue here.

    References

    This blog post makes reference to the following third party resources

  • Rohan Deshpande

    Announcing the AWS SDK for React Native

    We’re excited to announce the immediate availability of the developer preview of the AWS SDK for React Native. The source code is available on GitHub under the Apache 2.0 license.
     
    The SDK includes support for the following services:
    • Amazon S3 to store user data, including photos and videos, in the cloud. It uses the TransferUtility, which simplifies file transfers between your app and the cloud.
    • Amazon DynamoDB to store data into a NoSQL database.
    • AWS Lambda to run serverless code in the cloud without the need for backend infrastructure.
    • Amazon SNS to send and receive push notifications.
    The SDK core uses Amazon Cognito Identity as the authentication provider to comply with best practices for mobile app development.
     

    Getting Started with the SDK

    To include the SDK in your React Native application:
    1. Download the packages from Github.
    2. Add the services that you need into your package.json.
    3. Run npm install.
    Here is a sample package.json that uses AWS Lambda. 
     
    % cat package.json
{
  "name": "sample",
  "version": "0.0.1",
  "scripts": {
    "start": "node node_modules/react-native/local-cli/cli.js start"
  },
  "dependencies": {
    "aws-sdk-react-native-core": "../aws-sdk-react-native-core-0.0.1.tgz",
    "aws-sdk-react-native-lambda": "../aws-sdk-react-native-lambda-0.0.1.tgz",
    "react": "15.3.1",
    "react-native": "0.32.0"
  }
}
    See the GitHub repository for sample apps that demonstrate how to use the Cognito functionality to authenticate and the TransferUtility to transmit files to S3.
     

    Contributing to the SDK

    We welcome issue reports and contributions to the AWS SDK for React Native. Please report issues using the Github issue tracker. To contribute, submit a pull request to the GitHub repository with a description of your issue or suggested change. If this is a bug fix, please reference the issue and include steps to reproduce it.

     

  • Jeff Bailey

    Tracking and Remembering Devices Using Amazon Cognito Your User Pools

    Introduction

    With the general availability launch of Amazon Cognito Your User Pools, we introduced a new feature that enables device tracking and remembering. This feature provides insight into the usage of your app’s users and reduces the friction associated with multi-factor authentication (MFA). This blog post provides an overview of the feature, identifies the primary use cases, and describes how to set up the feature for your application.

     

    Use cases

    First, let’s take a look at some of the primary use cases for device remembering. The following examples are not exhaustive, but we use them in this blog post to illustrate the functionality.

    This feature enables developers to remember the devices on which end users sign in to their application. You can see the remembered devices and associated metadata through the console and by using the ListDevices and GetDevice APIs. In addition, you can build custom functionality using the notion of remembered devices. For example, with a content distribution application (e.g., video streaming), you can limit the number of devices from which an end user can stream their content.

    This feature works together with MFA to reduce some of the friction end users experience when using MFA. If SMS-based MFA is enabled for an Amazon Cognito user pool, end users must input a security code received via SMS during every sign-in in addition to entering their password. This increases security but comes at the expense of user experience, especially if users must get and enter a code for every sign-in. By using the new device remembering feature, a remembered device can serve in place of the security code delivered via SMS as a second factor of authentication. This suppresses the second authentication challenge from remembered devices and thus reduces the friction users experience with MFA.


    Console setup

    The following image shows how you can enable device remembering from the Amazon Cognito console.


     

    The specifics of these configurations shown above can be made clearer by going over some terminology first.
     

    Tracked

    When devices are tracked, a set of device credentials consisting of a key and secret key pair is assigned to every device. You can view all tracked devices for a specific user from the Amazon Cognito console device browser, which you can view by choosing a user from the Users panel. In addition, you can see some metadata (whether it is remembered, time it began being tracked, last authenticated time, etc.) associated with the device and its usage.
     

    Remembered

    Remembered devices are also tracked. During user authentication, the key and secret pair assigned to a remembered device is used to authenticate the device to verify that it is the same device that the user previously used to sign in to the application. APIs to see remembered devices have been added to new releases of the Android, iOS, and JavaScript SDKs. You can also see remembered devices from the Amazon Cognito console.
     

    Not Remembered

    A not-remembered device is the flipside of being remembered, though the device is still tracked. The device is treated as if it was never used during the user authentication flow. This means that the device credentials are not used to authenticate the device. The new APIs in the AWS Mobile SDK do not expose these devices, but you can see them in the Amazon Cognito console.

     

    Now, let’s go over the first configuration setting: Do you want to remember devices?
     

    No (default) – By selecting this option, devices are neither remembered nor tracked.
     

    Always – By selecting this option, every device used by your application’s users is remembered.
     

    User Opt-In – By selecting this option, your user’s device is remembered only if that user opts to remember the device.  This configuration option enables your users to decide whether your application should remember the devices they use to sign in, though keep in mind that all devices are tracked regardless. This is a particularly useful option for a scenario where a higher security level is required but the user may sign in from a shared device; for example, if a user signs in to a banking application from a public computer at a library. In such a scenario, the user requires the option to decide whether their device is to be remembered.

    The second configuration appears if you selected either Always or User Opt-In for the first configuration. It enables your application to use a remembered device as a second factor of authentication and thus suppresses the SMS-based challenge in the MFA flow. This feature works together with MFA and requires MFA to be enabled for the user pool. The device must first become remembered before it can be used to suppress the SMS-based challenge, so the first time a user signs in with a new device, the user must complete the SMS challenge; subsequently, the user does not need to complete the SMS challenge.

     

    A deeper dive on device identification

    As described previously, the device is identified and authenticated with a key and secret key credentials pair.

    The path to getting these credentials is as follows:

    1)      Every time the user signs in with a new device, the client is given the device key at the end of a successful authentication event.

    2)      From this key, the client creates a secret, using the secure remote password (SRP) protocol, and generates a salt and password verifier.

    3)      With that salt, verifier, and the key it was originally given, the client calls the ConfirmDevice API remotely. It is only then that Amazon Cognito begins tracking this device. During this entire flow, the secret remains on only the physical device.

    The AWS Mobile SDKs for Android, JavaScript, and iOS support this flow implicitly – you do not need to do anything to make device confirmation work. It happens in the background of user authentication.

    If you choose to have your users’ devices always remembered, then confirming the device marks it as remembered and begins tracking. If users must opt in to remember a device, confirming begins tracking the device as a not-remembered device. The response the client gets from that call indicates to the client that it must ask users if they want to remember the device. Each SDK can take a callback during the authentication call, which defines how users are asked if they want to remember the device. This authentication call consumes the UpdateDeviceStatus API. That API can be called any time to update the status as needed. The mobile SDKs use convenience wrappers around this method to make the calls more intuitive.
     

    Android:

    	// Create a callback handler to remember the device
	GenericHandler changeDeviceSettingsHandler = new GenericHandler() {
	    @Override
	    public void onSuccess() {
	        // Device status successfully changed
	    }

	    @Override
	    public void onFailure(Exception exception) {
	        // Probe exception for the cause of the failure
	    }
	};

	// To remember the device
	device.rememberThisDevice(changeDeviceSettingsHandler);
	// To not remember the device
	device.doNotRememberThisDevice(changeDeviceSettingsHandler);

     

    iOS:

    
	// To remember a device
	[self.user updateDeviceStatus:YES] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityUserUpdateDeviceStatusResponse*> * _Nonnull task) {
	    //Do something with task result here
	    return nil;
	}];

	// To not remember a device.
	[self.user updateDeviceStatus:NO] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityUserUpdateDeviceStatusResponse*> * _Nonnull task) {
	    //Do something with task result here
	    return nil;
	}];

    JavaScript:

    	cognitoUser.setDeviceStatusRemembered({
	    onSuccess: function (result) {
	        console.log('call result: ' + result);
	    },

	    onFailure: function(err) {
	        alert(err);
	    }
	});

	cognitoUser.setDeviceStatusNotRemembered({
	    onSuccess: function (result) {
	        console.log('call result: ' + result);
	    },

	    onFailure: function(err) {
	        alert(err);
	    }
	});

    The credentials provided to the device should be persistent and will be stored by the AWS Mobile SDKs, so any logic you build on top of the device key as an identifier can assume it will not change. The only way it could change is if the user wipes the device’s storage, if the user uninstalls the application, or if the ForgetDevice API is called for a device (this API removes all tracked devices for a user). If any of those occur, the next authentication treats the device as if it had never been used before.

    If a device is remembered, the device credentials are authenticated as part of the user authentication flow, using the SRP protocol. This authentication verifies that the key the service was provided is one that it generated itself, from the user it was generated for, and from the device it was given to.

    A successful authentication by a user generates a set of tokens – an ID token, a short-lived access token, and a longer-lived refresh token. The access token only works for one hour, but a new one can be retrieved with the refresh token, as long as the refresh token is valid. With device tracking, these tokens are linked to a single device. If a refresh token is used on any other device, the call fails. In a scenario where, for example, a device is stolen, the ForgetDevice API can be used to forget that specific device, and as a result, all future calls to revalidate that device’s refresh tokens will fail.
     

    How can you use this device identifier?

    There are a few APIs exposed on the client SDKs that enable you to see the remembered devices for the user that is currently signed in. Users must be signed in to view their devices because all APIs are authenticated with an access token.

    First, if you want to get a single device’s metadata, you call GetDevice as shown in the following examples.
     

    Android:

    	DevicesHandler getDeviceHandler = new DevicesHandler() {
	    @Override
	    public void onSuccess(List<CognitoDevice> devices) {
	        // This list will have one device in it, and will update the
	        // current device (currDevice)
	    }

	    @Override
	    public void onFailure(Exception exception) {
	        // Check exception for the cause of failure.
	    }
	};
	currDevice.getDevice(getDeviceHandler);

	// If you want to get the current device’s metadata
	user.thisDevice();


    iOS:

    	[self.user getDevice] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityUserGetDeviceResponse *> * _Nonnull task) {
	    //Do something with task result here
	    return nil;
	}];

    JavaScript:

    	cognitoUser.getDevice({
	    onSuccess: function (result) {
	        console.log('call result: ' + result);
	    },

	    onFailure: function(err) {
	        alert(err);
	    }
	});

    If you want to list all remembered devices for a user, you call the ListDevics API.

    Android:

    	DevicesHandler listDevicesHandler = new DevicesHandler() {
	    @Override
	    public void onSuccess(List<CognitoDevice> devices) {
	        // devices contains the list of all devices that are remembered
	    }

	    @Override
	    public void onFailure(Exception exception) {
	       // Check exception for the cause of failure.
	    }
	};

	user.listDevices(listDevicesHandler);

    iOS:

    	//The first parameter is page size, second is paginationToken from previous call
	[self.user listDevices:10 paginationToken:nil] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityUserListDevicesResponse *> * _Nonnull task) {
	    //Do something with task result here
	    return nil;
	}];

    JavaScript:

    	cognitoUser.listDevices(limit, paginationToken, {
	    onSuccess: function (result) {
	        console.log('call result: ' + result);
	     },

	    onFailure: function(err) {
	        alert(err);
	    }
	});


    If a user wants to stop tracking a device that is currently remembered, you call the ForgetDevice API.
     

    Android:

    	DevicesHandler forgetDeviceHandler = new DevicesHandler() {
	    @Override
	    public void onSuccess(List<CognitoDevice> devices) {
	        // this will forget whatever currDevice is. If it’s the
	        // physical device, it will also clear the local tokens.
	    }

	    @Override
	    public void onFailure(Exception exception) {
	        // Check exception for the cause of failure.
	    }
	};

	currDevice.forgetDevice(forgetDeviceHandler);

    iOS:

    	[self.user forgetDevice] continueWithSuccessBlock:^id _Nullable(AWSTask* _Nonnull task) {
	    //Do something with task result here
	    return nil;
	}];

    JavaScript:

    	cognitoUser.forgetDevice({
	    onSuccess: function (result) {
	         console.log('call result: ' + result);
	     },

	     onFailure: function(err) {
	         alert(err);
	     }
	});



    From the console, if you search for a user or choose a user that is on the user list, you can see every device tracked for that user with its key, name, the IP used when last authenticated, whether or not the device is remembered, the AWS SDK it used, and the time it last authenticated.

     

     

    Limiting devices per user

    You can use this feature if, for example, you are developing a content distribution app and want to limit the number of devices that users can connect to their account.

    To enable this use case, we have included an extra parameter in our inputs to our post-authentication AWS Lambda function: newDeviceUsed. It is a Boolean flag that is only true if you have device remembering turned on and if the device being used to authenticate is a new device.

    With this small addition, you can set a maximum for the number of devices that can be linked to a user’s account. Within your post-authentication Lambda hook, you can call the AdminListDevices API to count the number of devices currently linked if the newDeviceUsed flag is set to true. If it is over your determined limit, you fail the call, which then fails the authentication.

     

    Conclusion

    As you can see, integrating device remembering into your mobile and web applications is straightforward using the AWS Mobile SDKs. Device remembering enables you to create an experience that is designed to provide security and a user-friendly experience for your users. We'd love to hear how you plan to use this feature in your applications, so feel free to leave a comment to share other uses for this feature.

    If you encounter issues or have comments or questions, please leave a comment, visit our forums, or post on Stack Overflow. 

     

  • Karthik Saligrama

    AWS Mobile Hub Helper Code for iOS is now Available on GitHub

    In March 2016 we announced Swift support for AWS Mobile Hub. To make it easier for developers to integrate, we moved the code into a single framework. A side effect of that move was that the source code was no longer included in the project download. Customers could not update the source code of the framework if they wanted to extend the features AWS Mobile Hub already supports.

    Last week, we open-sourced the AWS Mobile Hub helper code on GitHub. You can find the source here and the API reference documentation here. To download the binary (framework) please continue to use the AWS Mobile Hub Console. From your AWS Mobile Hub project, choose Build, choose iOS Obj-C or iOS Swift, and download the source package.

    Building the Source

    If you decide to make changes to the source code, you can build the framework using the scripts located here. Here are the steps:

    1) Clone the repo https://github.com/aws/aws-mobilehub-helper-ios.git in any directory using:

    	git clone https://github.com/aws/aws-mobilehub-helper-ios.git

    2) Change the directory to cd aws-mobilehub-helper-ios/. The Source code uses CocoaPods for dependency management. You can install CocoaPods by using sudo gem install cocoapods. Run Pod Install from the root directory. This installs all of the dependencies for the project. After the installation is complete, you should get the following message:

     

    	Analyzing dependencies Downloading dependencies
	Installing AWSCognito (2.4.7)
	Installing AWSCore (2.4.7)
	Installing AWSLambda (2.4.7)
	Installing AWSS3 (2.4.7)
	Installing AWSSNS (2.4.7)
	........
	Integrating client project Sending stats Pod installation complete!
	There are 7 dependencies from the Podfile and 14 total pods installed.

    3)You can now run the following scripts from your project root directory using

    	./Scripts/GenerateHelperFramework.sh

    This generates a static framework in the <ProjectRoot>/builtframework/framework and you can include it in your project. If you decide to update the version of any dependency, make sure that the framework file for that dependency is also updated in your project.

    Contributing

    You can contribute to AWS Mobile Hub helper code by submitting pull requests on our GitHub repo. However, there are a few restrictions. If you would like to add an entirely new feature, submit feedback on the console for the new feature, using the feedback link on the bottom left corner of the console. Everything else, like minor patches and bug fixes, can be via pull requests.

  • Rob Lipschutz

    Find, Try, and Purchase Mobile Software in AWS Marketplace

    AWS Marketplace has worked with ISVs throughout our ecosystem to introduce new mobile software in AWS Marketplace throughout the past several months. This is software that helps enterprises, mid-market companies, and startups create and manage mobile apps for their customers or employees.

    The Mobile Factory

    With more than 30 new mobile products from over 20 different ISVs categorized by the three phases of the mobile application development process: Build & Launch, Secure & Integrate, and Launch & Manage, you’ll find software options for every phase of your project. Check out the AWS Marketplace Mobile Factory Web Page where products in each stage are highlighted with links to their product listing page in AWS Marketplace. You’ll find products in easy-to-deploy Amazon Machine Images (AMIs) and SaaS, paid and open source, and products suitable for startups or large enterprises. We call this the AWS Marketplace Mobile Factory because AWS Marketplace provides the components to help you construct and launch Mobile Apps more efficiently.

    AWS Marketplace Mobile Factory: Mobile Software for the Entire Mobile App Lifecycle

    Product Highlights

    For example, you can find enterprise mobile frameworks from Kony to build mobile apps that connect to back-end systems and innovative stacks from Bitfusion for integrating video, deep learning, and imaging into mobile apps by off-loading these compute intensive tasks to AWS compute services. You can find open source software such as Phone Gap, Cordova, and Ionic from GlobalSolutions available as a complete stack that installs in 2 clicks into your AWS environment. For testing before and after deployment, you’ll find HPE’s suite of products including StormRunner Load and AppPulse Mobile. For securing Apps, Proofpoint makes its Mobile Defense product available in AWS Marketplace. You’ll also find listings for Apigee Edge, a sophisticated API management system, and a number of analytics and prediction tools like New Relic, Arimo, and AppDynamics.

    AWS Marketplace Web site

    Integration with AWS

    AWS Marketplace software extends and complements AWS Mobile Services and AWS services. For example, Bitfusion’s products can leverage the specialized g2.2xlarge and g2.8xlarge Amazon EC2 instances for its media tasks and Apigee Edge works together with AWS Lambda. All products run on EC2 instances within a customer’s AWS infrastructure or as a SaaS offering leveraging AWS infrastructure.

    Given your specific requirements and the myriad of products available, it’s helpful to have a place where you can quickly try software that runs on AWS. Flexible pricing for many listings includes pay as you go hourly pricing, and many listings have free trials (AWS usage fees may apply) to get started. These pricing options give AWS customers the opportunity to evaluate products more cost-effectively. This flexibility and reversibility makes AWS Marketplace a great place to experiment for Agile developers.

    Please send your questions or suggestions for mobile software in AWS Marketplace to aws-marketplace-mobile@amazon.com. If you are an ISV with a mobile product, check out the informative blog post “How to List Your Product in AWS Marketplace” written by Suney Sharma on the AWS Partner Network (APN) blog.

  • Georgie Mathews

    Amazon Mobile Analytics Auto Export to Amazon S3 - Feature Update

    Amazon Mobile Analytics Auto Export to Amazon S3 accumulates and exports events sent to the Amazon Mobile Analytics service from your mobile and web applications into your own Amazon S3 bucket, within one hour from when we receive the event. This allows you to access the full data being recorded by your application to perform additional detailed analysis in addition to the analytics automatically produced in the Amazon Mobile Analytics console, such as Daily Active Users (DAU), Monthly Active Users (MAU), Average Revenue per Daily Active User and other out-of-the-box and custom metrics.

     

    What's New?

    We're making feature improvements to how data is processed after we receive it. Before these changes, files were written three times to ensure all data are published to your Amazon S3 bucket. Going forward, files will generally be written only a single time which will reduce the inbound bandwidth to your Amazon S3 bucket. This will also reduce the average amount of time it takes for Auto Export to Amazon S3 to deliver files into your Amazon S3 bucket. If you are an existing customer of this feature, make sure to read our forum announcement regarding a small change to how the files are named. Please note that the structure of the files is not changing and there are no changes in how the Auto Export to Amazon Redshift feature works.

     

    How do I start using it?

    If you're already using Amazon Mobile Analytics but have not enabled Auto Export to Amazon S3, log in to AWS and navigate to the Amazon Mobile Analytics console to enable the feature for one or more of your applications.  You can also choose to have your data exported to Amazon Redshift while you're there. You can find the steps to enable Auto Export here.

    If you haven't integrated Amazon Mobile Analytics into any of your applications yet, check out our User Guide and get your first Android, iOS, JavaScript, Unity, Xamarin, or custom application integrated today!

     

    FAQs

    1. Which development platforms do you support?

    We have SDKs to integrate with the following platforms: iOS, Android, JavaScript, Unity, and Xamarin. We also support REST API access.

     

    2. How do I export data collected from before I enabled Auto Export?

    At this time, the Amazon Mobile Analytics Auto Export to Amazon S3 feature only supports data export on a forward basis.  Data collected prior to enabling this feature is not available for export to Amazon S3 or Amazon Redshift, however, it is used to calculate the analytic metrics that are accessible via the Amazon Mobile Analytics console.

     

    3. How are the Amazon S3 file names generated by Auto Export to Amazon S3 changing?

    The current file name pattern is as follows:

    <bucket-name>/awsma/events/<appId>/<YYYY>/<MM>/<DD>/<hh>/<appId>-<mm>-part-<partNum>.gz

    After the change, the file name pattern will be:

    <bucket-name>/awsma/events/<appId>/<YYYY>/<MM>/<DD>/<hh>/<appId>-<mm>-part-<partNum>-<hexCode>.gz

     

  • Asha Chakrabarty

    Test User Interfaces in iOS Apps with XCTest UI and AWS Device Farm

    With AWS Device Farm, you can quickly start testing your Android, iOS, and FireOS apps on real devices in the AWS Cloud. Choose to start an interactive session with a device or run automated tests on many devices at once. AWS Device Farm will provide the results of your tests including pass/fail status, logs, performance metrics, screenshots, and videos.

    Introduction to XCTest UI

    As of Xcode 7, you can access UI testing capabilities (XCUI) integrated into the Xcode IDE. This functionality allows you to find and interact with UI elements in your app and confirm their properties and states. A few new features make it possible for you to programmatically test and exercise the UI of an iOS app with:

    • New Xcode target type for UI tests:

    To set up a UI test in Xcode, you create an Xcode target with the iOS UI Testing Bundle template. The Xcode target type fulfills the special requirements required by the UI tests, including launching a proxy for the application in a separate process and providing accessibility permissions.

    • UI testing APIs include three key classes:
      • XCUIElementQuery: Every UI element is backed by the ability to query its properties. For this reason, each XCUIElement must be unique.
      • XCUIElement: A proxy object for a UI element that is represented as types (for example, a cell or a button).
      • XCUIApplication: An instantiation of your application object that forms the origin for finding UI elements.
    • UI recording:

    This allows you to record interactions with your app’s user interface. Xcode will transform these interactions into source code that can be included in your existing tests or to create new tests. 

    AWS Device Farm now allows you to run the UI Testing feature incorporated in Xcode 7 on real devices in the AWS Cloud. In this post, we will walk you through how to create an XCTest UI test, package it for testing on AWS Device Farm, schedule a run, and view test results from real devices in the cloud.

    Prerequisites

    • You'll find the sample iOS app used in this post on AWS Labs on GitHub.
    • UI Testing was introduced in Xcode 7 and iOS 9, so be sure to update accordingly.
    • iOS devices must be enabled for development and connected to a host running Xcode.
    • It is assumed that you have created the .ipa file for the sample iOS app before you schedule a run in AWS Device Farm.

    Step 1: Create a UI Test for the AWS Sample iOS App

    After you have downloaded and opened the sample app in Xcode, build the project. After the build is successful, you will create a new a target type for the UI tests.

    Your project navigator should look like the following:

    With UI testing, you can record interactions within your app and Xcode will write the code required to re-enact those interactions in your test. You will still need to use XCTAssert to add your test assertions. You can record interactions with your UI by pressing the record button (the small red dot at the bottom left corner of the editor pane).

    Copy the following UI test code to your AWSDeviceFarmiOSReferenceAppUITests.m implementation file.

    #import 

@interface AWSDeviceFarmiOSReferenceAppUITests : XCTestCase

@end

@implementation AWSDeviceFarmiOSReferenceAppUITests

- (void)setUp {
    
    [super setUp];
    self.continueAfterFailure = NO;
    [[[XCUIApplication alloc] init] launch];
    
}


- (void)tearDown {
    
    [super tearDown];
}


- (void)testNativeInput {
    
    XCUIApplication *app = [[XCUIApplication alloc] init];
    XCUIElementQuery *tabBarsQuery = app.tabBars;
    [tabBarsQuery.buttons[@"Native"] tap];
    
    XCUIElementQuery *collectionViewsQuery = app.collectionViews;
    [collectionViewsQuery.staticTexts[@"Table of elements"] tap];
    [app.navigationBars[@"ElementsTableView"].buttons[@"Menu"] tap];
    [collectionViewsQuery.staticTexts[@"Scrolling View"] tap];
    [app.navigationBars[@"Scrolling View"].buttons[@"Menu"] tap];
    [tabBarsQuery.buttons[@"Home"] tap];
    
}


- (void)testNestedView {
    
    
    XCUIApplication *app = [[XCUIApplication alloc] init];
    XCUIElementQuery *tabBarsQuery = app.tabBars;
    [tabBarsQuery.buttons[@"More"] tap];
    [app.staticTexts[@"Nested"] tap];
    
    XCUIElement *moreNavigationBar = app.navigationBars[@"More"];
    XCUIElement *nextButton = moreNavigationBar.buttons[@"Next"];
    [nextButton tap];
    [nextButton tap];
    [nextButton tap];
    
    XCUIElement *backButton = [[[moreNavigationBar childrenMatchingType:XCUIElementTypeButton] matchingIdentifier:@"Back"] elementBoundByIndex:0];
    [backButton tap];
    [backButton tap];
    [backButton tap];
    [moreNavigationBar.buttons[@"More"] tap];
    [tabBarsQuery.buttons[@"Home"] tap];
    
}


- (void)testAlertControl {
    
    
    XCUIApplication *app = [[XCUIApplication alloc] init];
    XCUIElementQuery *tabBarsQuery = app.tabBars;
    [tabBarsQuery.buttons[@"More"] tap];
    [app.staticTexts[@"Alerts"] tap];
    [app.buttons[@"Modal"] tap];
    [app.buttons[@"OK"] tap];
    [app.buttons[@"Alert"] tap];
    [app.alerts[@"Alert"].collectionViews.buttons[@"OK"] tap];
    [app.navigationBars[@"More"].buttons[@"More"] tap];
    [tabBarsQuery.buttons[@"Native"] tap];
    [app.collectionViews.staticTexts[@"Image Gallery"] tap];
        
}

@end

    Before packaging your test for AWS Device Farm, be sure to build the project with Xcode. Use the Product/Build for Running option select an iOS device. Keep in mind that the Build Active Architecture setting for your app and your UI test targets should be the same.

    Step 2: Package Your Test for AWS Device Farm

    When packaging your test for upload to AWS Device Farm, make sure your iOS XCTest UI Runner test runner bundle is contained in a correctly formatted .ipa file. For more information, see the AWS Device Farm documentation. You can also view the creation of an .ipa file on AWS Labs on GitHub.

    Make sure that you package your test in the Payload folder under debug-iphoneos as shown here. In the following screenshot, we renamed the resulting zip file of the Payload folder to UITest.ipa for easier file management.

    Step 3: Schedule a Run in AWS Device Farm

    Sign in to the AWS Device Farm console and create a run under a new or existing project. Upload the .ipa file of the sample app.

    In the next step, you will choose XCTest UI as the test type and upload the .ipa file you created in step 2.

    Select the devices on which you'd like to test. If you like, you can create a new device pool for your test run to reuse in subsequent runs.

    Finally, review and start the test run.

    Step 4: View XCTest UI Test Results

    When your test run is complete, you will see the test results summary.

    Choose a device to examine its test suites. Here we are reviewing the test suite results for an Apple iPhone 5s and Apple iPhone 6 device.

    The results for each device will contain screenshots, video recordings, performance data, and log files that can be downloaded for further review.

    Conclusion

    We are always happy to hear your feedback. Feel free to leave your feedback, including questions, in the comments or on our developer forum.

    Happy testing!

  • Arjun Cholkar

    Introducing Worldwide SMS Messaging

    Introduction

    Earlier this week, Amazon SNS released worldwide SMS delivery and made it available in six AWS Regions. Worldwide SMS delivery means that you can now send SMS text messages directly to mobile phone numbers in more than 200 countries. Along with this expansion, SNS also enabled default “opt-in” of recipient phone numbers. This creates more possibilities for SMS messages, such as those needed for multi-factor authentication (MFA) or one-time passcodes.

    In this blog post, we will cover notable changes from the previous SMS offering and highlight the new features. We’ll also describe SMS account-level configuration, show how to set up delivery status, and describe the new SMS API calls and message attributes.

    What’s new with worldwide SMS delivery?

    The following table shows the previous SMS offering and the features and options that are now available with the new worldwide SMS delivery from Amazon SNS.

    SMS (former capability)

    Worldwide SMS (new)

    US-based phone numbers only.

    Global support of phone numbers in 200+ countries. The full list of supported countries can be found here.

    Each phone number required “opt-in” from recipient prior to the developer sending messages.

    No opt-in required.

    SMS delivery available in the us-east-1 Region only.

    Available in the following AWS Regions:

    us-east-1: US East (N. Virginia)

    us-west-2: US West (Oregon)

    eu-west-1: EU (Ireland)

    ap-northeast-1: Asia Pacific (Tokyo)

    ap-southeast-1: Asia Pacific (Singapore)

    ap-southeast-2: Asia Pacific (Sydney)

    All US-based phone numbers required a subscription to an SNS topic with a display name; developers published to the topic.

    Developers can now directly publish to a phone number without requiring subscriptions to an SNS topic. They can also subscribe the phone number to an SNS topic and publish to the topic.

    N/A

    Manage opted-out phone numbers in the AWS Management Console, API, CLI or SDK. More details here.

    Delivery status available for application, Lambda, HTTP, and SQS protocols only.

    SMS has its own delivery status that can be configured per region. Delivery status can be enabled in the AWS Management Console, the AWS CLI, or SDK.

    N/A

    Optionally set account (maximum spend per month) and message level (maximum spend per message) spend limits.

    N/A

    Optional Daily SMS Usage Reports (in CSV) for successful and failed SMS deliveries. Set-up instructions can be found here.

    All SMS text messages were delivered from the same Amazon short code: 30304.

    Amazon SNS uses a pool of long codes or short codes to send SMS notifications. Users will no longer receive messages from the 30304 short code. Additionally SNS sends messages from an AWS account to a phone number from the same long or short code (this is called the Sticky Sender ID).

    N/A

    With worldwide SMS delivery, developers can choose between transactional or promotional message types to optimize for high delivery success or cost savings. More details can be found here.

    Notable Changes to existing SMS subscriptions

    • All SMS phone numbers actively subscribed to an SNS topic will see a new long code or short code when a new message is delivered after June 28. After the new long/short code is established, recurring messages should come from the same code (though this is not guaranteed). This feature is called Sticky Sender ID.
    • When a user sends “STOP”, the phone number will not be unsubscribed from the SNS topic. Instead, the phone number is added to the new “opted out” list that you manage. The SMS phone number that is subscribed to the SNS topic will still show subscribed even after a “STOP” request. However, if you publish to the SNS topic for which the opted out phone number exists, the delivery will fail and the failed message will be logged to Amazon CloudWatch Logs (if you enabled delivery status, of course).

    SMS account-level configuration

    You can set account-level text messaging preferences in the Amazon SNS console. In messaging preferences, you can specify account-level SMS message type, specify the spend limit, enable delivery status, provide a sender ID, and specify an Amazon S3 bucket to receive daily SMS delivery reports.

    Here’s what the configuration screen looks like, including a description for each preference.

     

    Delivery status

    What is SNS delivery status?

    SNS delivery status logs successful and unsuccessful SMS deliveries to Amazon CloudWatch Logs. Delivery status for SMS enables developers to collect logged data on successful and unsuccessful delivery attempts of their SMS messages to individual phone numbers. It also provides information about dwell times in Amazon SNS. Dwell times indicate: 1) how long it takes to deliver the message to the destination carrier from the time the message was published to SNS, and 2) how long it takes for the recipient carrier to acknowledge delivery of that message from the time the message was published to SNS. In addition, the price per message is logged so that you can manage your SMS costs.

    Note: Delivery status plays a very important role in troubleshooting SMS deliverability. If you have issues with deliverability, consider enabling and configuring delivery status so that you can quickly identify and troubleshoot the issue.

    Enabling delivery status

    You can enable the delivery status feature for SMS with the Amazon SNS console, the AWS CLI, or the AWS SDKs. The simplest way is to enable delivery status using the SNS console, as described next.

    Enabling SMS delivery status using the Amazon SNS console

    Step 1: Log in to the Amazon SNS console.

    Step 2: Navigate to Text Messaging (SMS).

    Step 3: Select Create IAM role next to Default IAM role for success feedback.

    Step 4: On the SNS is requesting permission to use resources in your account page, choose Allow. This allows Amazon SNS to gain write access to Amazon CloudWatch Logs on your behalf.

    escription: Allow Access

    You should now see an IAM role as shown in the following example:

    https://cdn.amazonblogs.com/mobile_awsblog/images/sms-iam-role.png

    Example CloudWatch Logs

    Delivery status for SMS creates two CloudWatch Log Groups: Successful and Failed. The groups have the following format:

    Successful: sns/<region>/<accountID>/DirectPublishToPhoneNumber

    Failed: sns/<region>/<accountID>/DirectPublishToPhoneNumber/Failure

    Note: If one of the groups does not exist, then no logs have been delivered to that group, or the IAM role assumed by SNS does not have permission to write to CloudWatch Logs.

    Example log for successful SMS delivery

    The delivery status log for a successful SMS delivery looks like the following example:

    Example log for failed SMS delivery

    The delivery status log for a failed SMS delivery looks like the following example:

    New APIs for SMS worldwide delivery

    Along with the announcement of worldwide SMS delivery, there are new API calls and attributes for setting SMS preferences and text message delivery.

    SMS Account Preferences

    The following are the new API calls for setting and getting account SMS preferences:

    SetSMSAttributes

    GetSMSAttributes

    The following are the new SMS account attributes for setting and getting SMS account preferences:

    DefaultSenderID, MonthlySpendLimit, DeliveryStatusIAMRole, DeliveryStatusSuccessSamplingRate, DefaultSMSType, and UsageReportS3Bucket.

    For all SMS attributes, see SetSMSAttributes and GetSMSAttributes in the Amazon Simple Notification Service API reference.

    Sending a message

    You can send an SMS text message through the SNS console, CLI, or SDK. Remember, you can now publish directly to the individual phone number without going through an SNS topic or first waiting for the user to opt in.

    Note: When you send an SMS message, specify the phone number using the E.164 format. E.164 is a standard for the phone number structure used for international telecommunication. Phone numbers that follow this format have a maximum of 15 digits. They are prefixed with the plus character (+) and the country code. For example, a U.S. phone number in E.164 format would appear as +1XXX5550100.

    To send an SMS message by using one of AWS SDKs, use the same SNS Publish action in the SDK that corresponds to the Publish request in the Amazon SNS API.

    To directly publish to a phone number, you'll use the new phoneNumber and message parameters of the Publish API.

    Java

    .withMessage(message) // Specify the text message sent to the mobile phone.

    .withPhoneNumber(phoneNumber) // Specify the phone number using the E.164 format.

    .withMessageAttributes(smsAttributes) // Specify one or more of the three new MessageAttributes shown next.

    JavaScript

    Message, PhoneNumber, and additional MessageAttributes

    var params = { "Message": value, "PhoneNumber": value }

    The following are the new MessageAttributes for the Publish API:

    AWS.SNS.SMS.SenderID  // (Optional) defaults to an SNS specified value, if not specified by the sender.

    AWS.SNS.SMS.MaxPrice // (Optional) defaults to no max price.

    AWS.SNS.SMS.SMSType // (Optional) defaults to "Transactional".

    Tip: For Java, you will apply your attributes to the PublishRequest object of the Amazon SNS client.

    Questions?

    Check out the SMS FAQ here.

    Resources

    Amazon SNS Developer Guide

    Amazon SNS SMS FAQ

    Amazon SNS Forum

     

    Happy text messaging!

  • Vinay Kushwaha

    Announcing SAML Support for Amazon Cognito

    Today, we are excited to announce support in Amazon Cognito for Security Assertion Markup Language (SAML) 2.0 authentication. SAML 2.0 is an XML-based open standard that is used to transfer authentication and authorization data between parties.

    Now developers can sign in users through their own SAML identity providers and provide secure access through Amazon Cognito to their AWS resources, such as Amazon S3 and Amazon DynamoDB. 

    With SAML support in Amazon Cognito, developers can also configure IAM roles to provide different permissions to different users and groups.

    This post covers how you can configure SAML for Amazon Cognito to authenticate your users and assign them to specific AWS IAM roles. 

    1. Configure your identity pool for a SAML provider

    To configure your identity pool to support a SAML provider, choose the SAML tab in the Authentication provider section of the Amazon Cognito console. If you want to use an existing SAML provider, select the provider and save the changes for the identity pool.

    To create a new SAML provider:

    • Choose the AWS IAM console link to go to the IAM console.
    • In the left pane, choose Identity Providers.
    • Choose Create Provider and then choose SAML in Provider Type.

    • Type a name for the SAML provider and choose the SAML metadata document file that you received from your SAML Identity Provider (IdP). This file typically includes the issuer's name, expiration information, and a certificate that can be used to validate the SAML assertion response received from the IdP. For Microsoft Active Directory Federation Services (AD FS) you can download it from
      https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml.
      For more information related to different SAML IdPs, see Integrating Third-Party SAML Solution Providers with AWS.

    2. Create roles

    Now you create roles that you want to associate with your end user.  Unlike other types of IdPs, when you use a SAML-based IdP with Cognito, you do not have to select authenticated role for your Cognito identity pool. However, you can choose Create new role next to the Authenticated role label in the Cognito console and allow it to create the correct trust relationship as a convenient way to start creating new IAM roles. You can further configure the role policy and trust policy by using the IAM Console. Refer to the Cognito developer guide to learn more about the role policy by using context keys available with Cognito. You can create as many roles as required by your application and configure your IdP to populate the role in SAML assertion response. The role received in the SAML assertion from your IdP will be used for vending the AWS credentials for your users.

    The trust policy for your role used by Cognito will look similar to the following policy:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Federated": "cognito-identity.amazonaws.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "cognito-identity.amazonaws.com:aud": "us-east-1:12345678-identity-pool-id-123abc"
        },
        "ForAnyValue:StringLike": {
          "cognito-identity.amazonaws.com:amr": "authenticated"
        }
      }
    }
  ]
}

    3. Configure your SAML IdP

    After you create the SAML provider with AWS and setup your IAM roles, you can configure your SAML IdP to add relying party trust between your IdP and AWS.  Many IdPs allow you to specify a URL from which the IdP can read an XML document that contains relying party information and certificates. For AWS, you can use https://signin.aws.amazon.com/static/saml-metadata.xml

    The next step is to configure the SAML assertion response from your IdP to populate the claims needed by AWS. For details on the claim configuration, see Configuring SAML Assertions for the Authentication Response. For instructions on how to configure many popular IdPs, see Integrating Third-Party SAML Solution Providers with AWS.

    4. Customize Roles

    Using SAML with Amazon Cognito Identity allows the IAM role to be customized for the end user.  You configure your organization's IdP in a way that it maps users or groups in your organization to the IAM roles you want those users to assume. The exact steps for performing the mapping depend on what IdP you're using. Essentially you will be configuring the claim attribute https://aws.amazon.com/SAML/Attributes/Role to get populated in the SAML assertion response. This attribute specifies one or more pairs of comma delimited roles and provider ARNs. These are the roles for which the user is allowed to get credentials.

    If multiple roles are received in the SAML assertion response, the optional customRoleArn parameter should be populated while calling getCredentialsForIdentity.  The role received in the customRoleArn parameter will be used if it matches a role in the SAML assertion claim. Your app will need to provide the logic or prompt the user to choose a role if multiple roles are included in the SAML assertion.

    The value of the https://aws.amazon.com/SAML/Attributes/RoleSessionName claim attribute is used for setting the role session name in the credentials vended by Amazon Cognito. Role session name is set to a generic value 'CognitoIdentityCredentials' by Amazon Cognito if your identity pool supports multiple SAML providers and multiple assertions are received in the logins map which have different values of RoleSessionName.

    5. Authenticate users with SAML IdP and get SAML assertion

    After you have set up your Amazon Cognito identity pool and SAML IdP, you are ready to authenticate the user against the SAML IdP and federate with Amazon Cognito. The SAML IdP issues a SAML assertion for the authenticated user. The base-64 encoded assertion response must be passed to Amazon Cognito as a value in the logins map. The key in this map will be the ARN of the SAML provider that you associated with your identity pool in step #1.

    To federate with SAML based IdP, you will need to determine the URL which is being used to initiate the login. AWS federation utilizes IdP-initiated login. In ADFS 2.0 URL takes the form of https://<fqdn>/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices

    The following describes how to extract the SAML assertion response from ADFS. 

    • Populate the IdP URL, username, and password in the following code. Connect to the IdP with NTLM authentication. This should return an HTML input form in the response, which will have a  SAML assertion as a value. The following example shows the Java code for this step.  For different SAML IdPs and platforms, this step might be different. Refer to the documentation from your SAML identity provider to learn how to get the SAML assertion response.
            String idpurl= "https://<fqdn>/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices";

        Authenticator.setDefault(new Authenticator() {
            @Override
            public PasswordAuthentication getPasswordAuthentication() {
                return new PasswordAuthentication(username, password.toCharArray());
            }
        });

        URL urlRequest = new URL(idpurl);
        HttpURLConnection conn = (HttpURLConnection) urlRequest.openConnection();
        conn.setDoOutput(true);
        conn.setDoInput(true);
        conn.setRequestMethod("GET");

        InputStream stream = conn.getInputStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(stream));

        StringBuilder response = new StringBuilder();
        String str;
        while ((str = reader.readLine()) != null) {
            response.append(str);
        }
        String html = response.toString();
    • After you receive the HTML response from the IdP, use the following example code to parse the response and extract the Base64-encoded SAML response from it. 
            DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
        Document document = builder.parse(new InputSource(new StringReader(html)));

        Element docElement = document.getDocumentElement();
        NodeList inputNodes = docElement.getElementsByTagName("input");
        if (inputNodes != null && inputNodes.getLength() > 0) {

            for (int i = 0; i <= inputNodes.getLength() - 1; i++)  {
                Node inputNode = inputNodes.item(i);
                NamedNodeMap inputNodeAttributes = inputNode.getAttributes();

                Map inputAttibuteMap = new HashMap();

                for (int j = 0; j <= inputNodeAttributes.getLength() - 1; j++) {
                    inputAttibuteMap.put(inputNodeAttributes.item(j).getNodeName(),
                            inputNodeAttributes.item(j).getNodeValue());
                }                
                if (inputAttibuteMap.get("name").equals("SAMLResponse")) {
                    // Base 64 encoded SAML Authentication response.
                    return inputAttibuteMap.get("value");
                }
            }
        }

    6. Use the SAML assertion to call Amazon Cognito

    The examples below show how to call Cognito with the SAML assertion on different platforms. Please note, only the Enhanced flow in Amazon Congito is supported with SAML based IdP.

    Java:

        AmazonCognitoIdentity client = new AmazonCognitoIdentityClient(new AnonymousAWSCredentials());
    // Get id request. This only needs to be executed the first time and the result should be cached.
    GetIdRequest idRequest = new GetIdRequest();
    idRequest.setAccountId("aws account id");
    idRequest.setIdentityPoolId("identity pool id");

    Map logins = new HashMap();
    logins.put("arn:aws:iam::aws account id:saml-provider/name", "base64 encoded assertion response");
    idRequest.setLogins(logins );
    GetIdResult idResp = client.getId(idRequest);
    String identityId = idResp.getIdentityId();

    // GetCredentialsForIdentity call.
    GetCredentialsForIdentityRequest credRequest = new GetCredentialsForIdentityRequest();
    request.setIdentityId(identityId);
    request.setLogins(logins);

    // If SAML assertion contains multiple roles, resolve the role by setting the custom role
    request.setCustomRoleArn("arn:aws:iam::aws account id:role/admin");

    GetCredentialsForIdentityResult credetialsResult = client.getCredentialsForIdentity(credRequest)

     

    Android

    If you are using the Android SDK you can populate the logins map with the SAML assertion as follows.

        Map logins = new HashMap();
    logins.put("arn:aws:iam::aws account id:saml-provider/name", "base64 encoded assertion response");
    // Now this should be set to CognitoCachingCredentialsProvider object.
    CognitoCachingCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(context, identity pool id, region);
    credentialsProvider.setLogins(logins);
    // If SAML assertion contains multiple roles, resolve the role by setting the custom role
    credentialsProvider.setCustomRoleArn("arn:aws:iam::aws account id:role/customRoleName");
    // This should trigger a call to Cognito service to get the credentials.
    credentialsProvider.getCredentials();

    iOS

    If you are using the iOS SDK you can provide the SAML assertion in your AWSIdentityProviderManager as follows.

        - (AWSTask<NSDictionary<NSString*,NSString*> *> *) logins {
        //this is hardcoded for simplicity, normally you would asynchronously go to your SAML provider 
        //get the assertion and return the logins map using a AWSTaskCompletionSource
        return [AWSTask taskWithResult:@{@"arn:aws:iam::aws account id:saml-provider/name":@"base64 encoded assertion response"}];
    }

    // If SAML assertion contains multiple roles, resolve the role by setting the custom role.
    // Implementing this is optional if there is only one role.
    - (NSString *)customRoleArn {
        return @"arn:aws:iam::accountId:role/customRoleName";
    }

     

    As you can see, integrating a SAML-based IdP with Amazon Cognito provides you flexibility to choose different roles to associate with your organizations’ users and groups to access AWS resources. It is easy to integrate your SAML IdP with Amazon Cognito. This integration enables you to leverage the identity management and data synchronization functionality provided by Amazon Cognito.

    We welcome your feedback on this feature.  For more information, see the SAML Identity Provider topic in the Amazon Cognito Developer Guide. You can reach us by posting to the Amazon Cognito forums.