Use Login with Amazon SDK with iOS

II: Integrate LwA in your apps

~
~

Follow the instructions below to use Login with Amazon SDK for iOS to pass a Login with Amazon (LWA) authorization code to your product. Your product can use this authorization code to obtain refresh and access token needed to make calls to DRS. The full sample code is available in the Amazon Dash GitHub repository.

LWA Version Note

Note that in this documentation, we are using LWA version 3.0.1. You can check the LWA version by adding the following line of code in the viewDidLoad method:

NSLog(@"LWA version: %@", [AMZNLWASDKInfo sdkVersion]);

The output should look similar to this:

2017-02-09 18:19:53.680040 test[1805:822020] LWA version: 3.0.1

Get the Authorization Code and Make Calls to DRS on iOS

  1. Navigate to Login with Amazon Getting Started for iOS and complete steps 1 through 5.
Teaser page

On step 5, you will be asked to add a "Login with Amazon" button. You should customise the look and feel of the button as per our Teaser page guidelines
  1. Obtain a new API key from the Security Profiles console. If you do not have a Security Profile, follow the steps in the Create an LWA Security Profile guide to create one.
  2. In the Manage drop-down menu, select iOS settings.

  3. In the Manage drop-down menu, select iOS settings.
  4. Provide your API key name and a Bundle ID.
  5. Click Show under the Key column to see your API key.

  6. Copy the new API key to your application Info.plist file.

  7. Add the following #import statement to your source file to import the Login with Amazon API:

     #import <LoginWithAmazon/LoginWithAmazon.h>
    
  8. Add the function that will perform the login:

    - (void)login
    {
        AMZNAuthorizationManager* manager = [AMZNAuthorizationManager sharedManager];
        AMZNAuthorizeRequest* request = [[AMZNAuthorizeRequest alloc] init];
        request.interactiveStrategy = AMZNInteractiveStrategyAuto;
        NSMutableArray* scopeObjectArray = [NSMutableArray array];
        NSString* requestScopes = @"dash:replenish";
        NSMutableDictionary* options = NSMutableDictionary.new;
        //YOUR_DEVICE_SERIAL_NUMBER – The serial number of the device you are associating with the DRS service. Only alphanumeric characters can be used [A-Za-z0-9], for a maximum string length of 50 characters.
        options[@"serial"] = @"DEVICE_SERIAL_NUMBER";
        //Set device model name. This is a "Device Model ID" in the Self Service portal.
        options[@"device_model"] = @"DEVICE_MODEL_NAME";
        // Set whether this registration should allow marketplaces that have not yet been certified.
        // For use in pre-release testing only, this flag must not be passed in by your released app in production.
        // SHOULD_INCLUDE_NON_LIVE should be 'true' or 'false', allows the registration to proceed using device capabilities that have not yet been certified by Amazon. You can use this parameter to test your system while awaiting Amazon certification.
        options[@"should_include_non_live"] = @"SHOULD_INCLUDE_NON_LIVE";
    
        // IS_THIS_A_TEST_DEVICE – Flag that indicates if this a test device or not. You will not be able to test devices without setting the `is_test_device` flag to true, but you must set it to false in production. Test devices will not place real orders
        // IS_THIS_A_TEST_DEVICE should be 'true' or 'false'
        options[@"is_test_device"] = @"IS_THIS_A_TEST_DEVICE";
    
        id<AMZNScope> drsScope = [AMZNScopeFactory scopeWithName:requestScopes data:options];
        [scopeObjectArray addObject:drsScope];
        request.scopes = scopeObjectArray;
        request.grantType = AMZNAuthorizationGrantTypeCode;
        // Set your code challenge.
        request.codeChallenge = @"YOUR_CODE_CHALLENGE";
        // Set code challenge method - "plain" or "S256".
        request.codeChallengeMethod = @"YOUR_CODE_CHALLENGE_METHOD";
        [manager authorize:request withHandler:[self requestLoginHandler]];
    }   
    
    - (AMZNAuthorizationRequestHandler)requestLoginHandler
    {
        AMZNAuthorizationRequestHandler requestHandler = ^(AMZNAuthorizeResult* result, BOOL userDidCancel, NSError* error) {
            if (error) {
                NSString* errorMessage = error.userInfo[@"AMZNLWAErrorNonLocalizedDescription"];
                NSLog(@"Error: %@", errorMessage);
                // handle login error
            }
            else if (userDidCancel) {
                // handle user cancellation
            }
            else {
                // Authentication was successful. Obtain the user profile data.
                NSString* authCode = result.authorizationCode;
                NSString* clientId = result.clientId;
                NSString* redirectUri = result.redirectUri;
                NSLog(@"\n code = %@ \n client ID = %@ \n redirect URI = %@", authCode, clientId, redirectUri);
                // request the access and the refresh token
            }
        };
        return [requestHandler copy]
    }
    

    For more information about YOUR_CODE_CHALLENGE and YOUR_CODE_CHALLENGE_METHOD please see the prerequisites section.

    You have completed the necessary preparation to make a POST request call to obtain the access and refresh tokens. The following steps will walk you through the process of making this call. This call can be made from your mobile application or DRS product. (In this documentation, we assume you will make that call on your DRS product.)

  9. Securely transfer the authorization code, client ID, and redirect URI to your product, using SSL.
  10. After the authorization code, client ID, and redirect URI are received on the product, the product can call Login with Amazon to exchange the authorization code for the access token and refresh token .

Obtain Refresh and Access Tokens using Authorization Code Grant

When making the call, the product needs to send a POST request to https://api.amazon.com/auth/O2/token and pass in the following parameters:

HTTP Header Parameters

  • Content-Type: application/x-www-form-urlencoded

HTTP Body Parameters

  • grant_type: authorization_code.
  • code: The authorization code string received from the iOS app.
  • redirect_uri: The redirect URI string received from the iOS app.
  • client_id: The client ID string received from the iOS app.
  • code_verifier: The code verifier string that was initially generated by the product.

Sample Request:

 POST /auth/o2/token HTTP/1.1
 Host: api.amazon.com
 Content-Type: application/x-www-form-urlencoded
 Cache-Control: no-cache
 code=YOUR-AUTHORIZATION-CODE&client_id=YOUR-CLIENT-ID&redirect_uri=YOUR-REDIRECT-URI&code_verifier=YOUR-CODE-VERIFIER&grant_type=authorization_code
 curl –X POST –d 'code=YOUR-AUTHORIZATION-CODE&client_id=YOUR-CLIENT-ID&redirect_uri=YOUR-REDIRECT-URI&code_verifier=YOUR-CODE-VERIFIER&grant_type=authorization_code' https://api.amazon.com/auth/O2/token

The response includes the following values:

  • access_token: The access token string.
  • refresh_token: The refresh token string.
  • token_type: The token type string.
  • expires_in: The number of seconds for which the access token is still valid.

Sample Response:

 HTTP/1.1 200 OK

 {
    "access_token": "Atza|IQEBLjAsAhRBejiZKPfn5HO2562GBt26qt23EA...",
    "expires_in": 3600,
    "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EsdqwqwdqdasdvferrE...",
    "token_type": "bearer"
 }

Request New Refresh and Access Tokens

The access token is valid for one hour. When the access token expires, or is about to expire, you can exchange the refresh token for a new access token.

  • Send a POST request to https://api.amazon.com/auth/o2/token with the following parameters:

HTTP Header Parameters

  • Content-Type: application/x-www-form-urlencoded

HTTP Body Parameters

  • grant_type: refresh_token
  • refresh_token: The refresh token used to request new access tokens.
  • client_id: The client ID string received from the iOS app.
  • client_secret: The security profile's client secret. This information can be found on the Amazon developer portal’s Login With Amazon page.

Sample Request

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
grant_type=refresh_token&refresh_token=Atzr|CIQEBLzAtAhUAibmh-1N0E&client_id=amzn1.application-oa2-
client.b91a...&client_secret=6963038c1c2063c33ab9eedc...

Sample Response

HTTP/1.1 200 OK
{
   "access_token": "Atza|IQEBLjAsAhQ3yD47Jkj09BfU_qgNk4...",
   "expires_in": 3600,
   "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EVztZJofMx...",
   "token_type": "bearer"
}

Next Step

Next, we will look at integrating Login with Amazon in your other companion apps.

To create… Use
A native Android app LwA SDK for Android
A native iOS app LwA SDK for iOS
A web app or hybrid app (e.g. Cordova) LwA for Web

If you have integrated LwA already, you may move onto the API section of our tutorial.