App-to-App Account Linking

// Example success response from the Alexa app
https://yourRedirectURL?code={Amazon Authorization code}&state={your state}

// Example success response from LWA
https://yourRedirectURL?code={Amazon Authorization code}&scope={permission scope}&state={your state}

// Example error response
HTTP 200
https://yourRedirectURL?error_description={Error description}&state={your state}&error={OAuth Error Code}

import Alamofire
import SwiftyJSON

class AlamofireHelper {

    // Your backend base URL from which you're requesting the URL
    static let BASE_URL = "https://exampleBackEndURL"
    
    /*! Get Alexa app Universal Link and LWA fallback URL
     @param userAccessToken for your backend server
     @param state maintained between client and server, caller should generate it 
     */
    static func getAlexaAppUrl(userAccessToken:String, state: String) -> DataRequest {
        let alexaAppUrl = "/alexaurl"
        let inputstate = "?state=" + state
        
        var urlRequest = URLRequest(url: URL(string: BASE_URL + alexaAppUrl + inputstate)!)
        urlRequest.addValue("Bearer " + userAccessToken, forHTTPHeaderField: "Authorization")
        return Alamofire.request(urlRequest)
    }
    
    private init() {}
}

// Call to your backend to get the authorization request URLs (Alexa app / LWA)
AlamofireHelper.getAlexaAppUrl(userAccessToken: savedSession.accessToken, state: StateHelper.generateState()).responseJSON {
    response in
    guard let status = response.response?.statusCode, 200..<300 ~= status else {
        self.createAlert(title: "Failed to get Alexa URL", message: "Failed to get Alexa URL")
        return
    }
    guard let responseValue = response.result.value else {
        self.createAlert(title: "Invalid response", message: "Invalid response")
        return
    }
    let reponseInJSON = JSON(responseValue)
    guard let companionApp = reponseInJSON["companionAppURL"].string,let lwaFallback = reponseInJSON["LWAFallBackURL"].string else {
        self.createAlert(title: "Error response", message: "Error response")
        return
    }
    guard let companionAppURL = URL(string: companionApp), let lwaFallbackURL = URL(string: lwaFallback) else {
        self.createAlert(title: "Incorrect URL format", message: "Incorrect URL format")
        return
    }
    // The openUniversalLinks code snippet can be found in another example
    self.openUniversalLinks(companionAppURL: companionAppURL, lwaFallbackURL: lwaFallbackURL)
}

import SafariServices

// Open the Alexa URL with option universalLinksOnly
// If it doesn't open the Universal Link, open the LWA fallback 
private func openUniversalLinks(companionAppURL: URL, lwaFallbackURL: URL) {
    UIApplication.shared.open(companionAppURL, options: [UIApplication.OpenExternalURLOptionsKey.universalLinksOnly:true]) {
        companionAppLaunched in
        if !companionAppLaunched {
            if #available(iOS 12.0, *) {
                WebSession.initWebAuthenticationSession(authURL: lwaFallbackURL)
            } else if #available(iOS 11.0, *) {
                WebSession.initAuthenticationSession(authURL: lwaFallbackURL)
            } else {
                let safariViewController =  SFSafariViewController(url: lwaFallbackURL)
                self.present(safariViewController, animated: true, completion: nil)}
        }
    }
}

// Web session
class WebSession {
    @available(iOS, introduced: 11.0, deprecated: 12.0)
    private static var authenticationSession: SFAuthenticationSession?
    
    @available(iOS 12.0, *)
    private static var webAuthenticationSession : ASWebAuthenticationSession?
    
    private static let CALLBACK_URL_SCHEME = "https://yourAppsUniversalLinkURL"
    
    @available(iOS, introduced: 11.0, deprecated: 12.0)
    static func initAuthenticationSession(authURL:URL) {
        if let session = authenticationSession {
            session.cancel()
        }
        self.authenticationSession = SFAuthenticationSession.init(url: authURL, callbackURLScheme: CALLBACK_URL_SCHEME, completionHandler:{
            (callBack:URL?, error:Error?) in
            //Callback and error handling
        })
        self.authenticationSession?.start()
    }
    
    @available(iOS 12.0, *)
    static func initWebAuthenticationSession(authURL:URL) {
        if let session = webAuthenticationSession {
            session.cancel()
        }
        
        self.webAuthenticationSession = ASWebAuthenticationSession.init(url: authURL, callbackURLScheme: CALLBACK_URL_SCHEME, completionHandler:{
            (callBack:URL?, error:Error?) in
            // Callback and error handling
        })
        self.webAuthenticationSession?.start()
    }
    
    private init(){}
}

import SafariServices

// Open Login with Amazon in Safari View controller
private func openSafariView(lwaFallbackURL: URL) {
    let safariViewController =  SFSafariViewController(url: lwaFallbackURL)
    self.present(safariViewController, animated: true, completion: nil)}
}

// Handler for Universal Links in AppDelegate
// Add this method to handle incoming Universal Links
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL else {
            return false
    }
    let handlers : [UniversalLinkHandler] = [AuthResponseHandler(), ErrorResponseHandler()]
    var validatedResponse : ValidatedResponse?
    for handler in handlers {
        if handler.canHandle(incomingURL: incomingURL) {
            validatedResponse = handler.getValidatedResponse()
            let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "linkingStatusScreen") as! LinkingStatusViewController
            initialViewController.response = validatedResponse
            self.window?.rootViewController = initialViewController
            self.window?.makeKeyAndVisible()
            return true
        }
    }
    return false
}

// Incoming Universal Links handler protocol
protocol UniversalLinkHandler {

    //Validate the incoming URL scheme
    func canHandle(incomingURL:URL)-> Bool
    
    //Get the validated response
    func getValidatedResponse() -> ValidatedResponse?
}

extension UniversalLinkHandler {
    func validateState(state:String)->Bool {
        return StateHelper.validateState(state: state)
    }
}

// Successfully receiving the Amazon Authorization code
class AuthResponseHandler : UniversalLinkHandler {

    private let AUTH_RESPONSE_PARAMETERS: Set = ["code", "state", "scope"]
    private var validatedResponse: ValidatedResponse?
    
    func canHandle(incomingURL: URL) -> Bool {
    
        guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
            let queryParameters = components.queryItems else {
                return false
        }
        
        var validatedParameters : [String: String] = [:]
        for queryParameter in queryParameters {
            //duplicated parameters in URL
            if validatedParameters.keys.contains(queryParameter.name) {
                return false
            }
            //Unrecognized parameters in URL
            if !AUTH_RESPONSE_PARAMETERS.contains(queryParameter.name) {
                return false
            }
            validatedParameters[queryParameter.name] = queryParameter.value
        }
        
        guard let code = validatedParameters["code"], let state = validatedParameters["state"] else {
            return false
        }
        
        //validated the state
        if !validateState(state: state) {
            self.validatedResponse = ErrorResponse(url: incomingURL,error: "Invalid state", errorDescription: "The request has invalid state")
            return true
        }
        
        self.validatedResponse = AuthResponse(url: incomingURL,code: code, state: state, scope: validatedParameters["scope"])
        return true
    }
    
    func getValidatedResponse() -> ValidatedResponse? {
        return validatedResponse
    }
}

// Error authorization response handler
class ErrorResponseHandler : UniversalLinkHandler {
    private let ERROR_RESPONSE_PARAMETERS: Set = ["error", "error_description", "state"]
    private var validatedResponse: ValidatedResponse?
    
    func canHandle(incomingURL: URL) -> Bool {
        guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
            let queryParameters = components.queryItems else {
                return false
        }
        
        // Validate all query parameters 
        var validatedParameters : [String: String] = [:]
        for queryParameter in queryParameters {
            // Duplicated parameters in URL
            if validatedParameters.keys.contains(queryParameter.name) {
                return false
            }
            // Unrecognized parameters in URL
            if !ERROR_RESPONSE_PARAMETERS.contains(queryParameter.name) {
                return false
            }
            validatedParameters[queryParameter.name] = queryParameter.value
        }
        
        guard let error = validatedParameters["error"], let errorDescription = validatedParameters["error_description"], let state = validatedParameters["state"] else {
            return false
        }
        
        // validate the state
        if !validateState(state: state) {
            self.validatedResponse = ErrorResponse(url: incomingURL,error: "Invalid state", errorDescription: "The request has invalid state")
            return true
        }
        
        self.validatedResponse = ErrorResponse(url: incomingURL, error: error, errorDescription: errorDescription)
        return true
    }
    
    func getValidatedResponse() -> ValidatedResponse? {
        return validatedResponse
    }
}

// Validated response
class ValidatedResponse {

    // Universal Link URL that launched the App
    private(set) var url: URL
    init (url: URL) {
        self.url = url
    }
}

// Amazon authorization code response per the OAuth2 specification 
class AuthResponse : ValidatedResponse{
    private(set) var code : String
    private(set) var state: String
    
    //scope will be returned in Login with Amazon, will not be present in Alexa Companion flow
    private(set) var scope: String?
    init(url:URL, code:String, state:String, scope: String?) {
        self.code = code
        self.state = state
        self.scope = scope
        super.init(url:url)
    }
}

// Error response per the OAuth2 specification 
class ErrorResponse : ValidatedResponse {
    private(set) var error : String
    private(set) var errorDescription: String
    init(url: URL, error:String, errorDescription:String) {
        self.error = error
        self.errorDescription = errorDescription
        super.init(url: url)
    }
}

import Foundation
import Security

class StateHelper {
    private static let STATE_VALID_FOR = 3600
    // Base64 (iOS + TimeStamp + Secure Random UUID)
    private static let NUMBER_OF_PARAMETER = 3
    
    static func generateState(session: Session)-> String {
        var buffer = Data(count: 30)
        let _ = buffer.withUnsafeMutableBytes {
            SecRandomCopyBytes(kSecRandomDefault, 30, $0)
        }
        let state = ("iOS." + String(Int64(Date().timeIntervalSince1970)) + "." + buffer.base64EncodedString()).encodeToURISafeBase64()
        
        // store state in session manager for future validation
        session.state = state
        LocalSessionManager.saveSession(session: session)
        
        return state
    }
    
    static func validateState(state: String) -> Bool {
        guard let originalState = LocalSessionManager.loadSession()?.state  else {
            return false
        }
        if state != originalState {
            return false
        }
        if let timeStampString = originalState.decodeFromURISafeBase64()?.split(separator: "."), timeStampString.count == NUMBER_OF_PARAMETER, let timeStamp = Int64(timeStampString[1]){
            if Int64(Date().timeIntervalSince1970) - timeStamp <= STATE_VALID_FOR {
                return true
            }
        }
        if let session = LocalSessionManager.loadSession() {
            session.state = nil
            LocalSessionManager.saveSession(session: session)
        }
        return false
    }
    
    private init() {}
}

extension String {
    func decodeFromURISafeBase64() -> String? {
        let base64String = String(self.map {
            // replace unsafe characters 
            character in
            if character == "." {
                return  "+"
            } else if character == "_" {
                return "/"
            } else if character == "-" {
                return "="
            }
            return character
        })
        guard let data = Data(base64Encoded: base64String) else {
            return nil
        }
        return String(data: data, encoding: .utf8)
    }
    
    func encodeToURISafeBase64() -> String {
        return String(Data(self.utf8).base64EncodedString().map{
            // replace back unsafe characters 
            character in
            if character == "+" {
                return  "."
            } else if character == "/" {
                return "_"
            } else if character == "=" {
                return "-"
            }
            return character
        })
    }
}

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code
&code=amazon authorization code 
&client_id=yourClientId
&client_secret=yourClientSecret
&redirect_uri=yourRedirectUri

HTTP 200
Content-Type: application/json
{
  "access_token": "AmazonAccessToken",
  "expires_in": "3600",
  "refresh_token": "YourRefreshToken",
  "token_type": "bearer"
}

const axios = require('axios');

// Amazon OAuth token request in the backend
const OAuthRequests = (function () {
    const header = {
        "headers": {
            "Content-Type": "application/json"
        }
    };

    const accessTokenBody = function (amazonAuthCode, state) {
        return {
            "grant_type": "authorization_code",
            "code": amazonAuthCode,
            "redirect_uri": config.skillConfig.redirect_uri,
            "client_id": config.skillConfig.client_id,
            "client_secret": config.skillConfig.client_secret
        };
    };

    return {
        accessTokenRequest: (authcode, state) => {
            return {
                header: header,
                body: accessTokenBody(authcode, state)
            }
        }
    }
})();

// Request the Amazon access/refresh tokens from the Amazon OAuth token server
function getAccessTokenByAuthcode(amazonAuthCode, state) {
    const accessTokenRequest = OAuthRequests.accessTokenRequest(amazonAuthCode, state);
    return axios.post(config.endpoints.oauthEndpoint, accessTokenRequest.body, accessTokenRequest.header);
}

POST /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: api.amazonalexa.com, api.eu.amazonalexa.com, api.fe.amazonalexa.com
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"
{
    "stage": "skill stage",
    "accountLinkRequest": {
      "redirectUri": "https://yourRedirectURI",
      "authCode": "Your user's authorization code from your authorization server",
      "type": "AUTH_CODE"
    }
}

HTTP 201
Content-Type: application/json
{
  "skill": {
    "stage": "your skill stage",
    "id": "your skill id"
  },
  "user": {
    "id": "User ID"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "status": "ENABLED"
}

const _ = require('lodash');
const axios = require('axios');
const {config} = require('../config/skillconfig');
const {getAccessTokenByAuthcode} = require('./oauthrequests');

// Request to the Alexa Skill Activation API in the backend
const AlexaServiceRequest = (() => {
    const header = (amazonAccessToken) => {
        return {
            "headers": {
                "Content-Type": "application/json",
                "Authorization": "Bearer " + amazonAccessToken
            }
        };
    };

    const body = (userAuthCode) => {
        return {
            "stage": config.skillConfig.stage,
            "accountLinkRequest": {
                "redirectUri": config.skillConfig.redirect_uri,
                "authCode": userAuthCode,
                "type": "AUTH_CODE"
            }
        }
    }

    return {
        createEnablement: (amazonAccessToken, userAuthCode) => {
            return {
                header: header(amazonAccessToken),
                body: body(userAuthCode)
            }
        }
    }
})();

function createEnablementWithAccountLink(amazonAuthCode, userAuthcode, state) {
   
    // Exchange Amazon OAuth Code for Amazon Access Token
    const tokenPromise = getAccessTokenByAuthcode(amazonAuthCode, state);
    return tokenPromise.then((res) => {
        if (!_.has(res, 'data.access_token')) {
            throw Error("Amazon AccessToken is invalid");
        }
        console.log(res);
        const amazonAccessToken = res.data.access_token;

        // Call the Alexa Skill Activation API to create enablement 
        const createEnablementRequest = AlexaServiceRequest.createEnablement(amazonAccessToken, userAuthcode);
        return sendPostRequests(config.endpoints.alexaServiceEndpoints, createEnablementRequest.body, createEnablementRequest.header);
    });
}

// Post enablement to the Alexa Skill Activation API 
function sendPostRequests(endpoints, body, header) {
    var alexaServicePromises = []
    
    // Post for each Alexa Skill Activation API regional endpoint for the user
    endpoints.forEach((endpoint)=> {
        alexaServicePromises.push(axios.post(endpoint, body, header));
    });
    return new Promise((resolve, reject)=> {
        var failures = 0;
        alexaServicePromises.forEach((promise)=> {
            promise.then((res)=> {
                if (res.status == 201) {
                    resolve(res.data);
                } else {
                    if (++failures == alexaServicePromises.length) {
                        reject(res.data);
                    }
                }
            }).catch((err)=> {
                if (++failures == alexaServicePromises.length) {
                    reject(err.data);
                }
            })
        })
    });
}

import UIKit

class LinkingStatusViewController: UIViewController {
    
    @IBOutlet weak var header: UILabel!
    @IBOutlet weak var status: UILabel!
    @IBOutlet weak var closeButton: UIButton!
    @IBOutlet weak var indicator: UIActivityIndicatorView!
    
    var response : ValidatedResponse?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        if let res = self.response {
            passValidatedResponse(validatedResponse: res)
        }
    }
    
    private func updateView(header:String, status:String, animating: Bool,closeButton:Bool) {
        if animating {
            self.indicator?.startAnimating()
        } else {
            self.indicator?.stopAnimating()
        }
        self.indicator?.isHidden = !animating
        self.header?.text = header
        self.status?.text = status
        
        self.closeButton.isEnabled = closeButton
        if closeButton {
            self.closeButton.backgroundColor = #colorLiteral(red: 0.1960784314, green: 0.6039215686, blue: 0.8392156863, alpha: 1)
        } else {
            self.closeButton.backgroundColor = #colorLiteral(red: 0.6000000238, green: 0.6000000238, blue: 0.6000000238, alpha: 1)
        }
    }
}

extension LinkingStatusViewController {
    func passValidatedResponse(validatedResponse: ValidatedResponse) {
        if validatedResponse is AuthResponse {
            let response: AuthResponse = validatedResponse as! AuthResponse;
            updateView(header: "Status", status: "Loading", animating: true, closeButton: false)
            usingAuthCodeToGetAccessToken(amazonAuthCode: response.code)
        } else if (validatedResponse is ErrorResponse) {
            let response: ErrorResponse = validatedResponse as! ErrorResponse;
            updateView(header: response.error, status: response.errorDescription, animating: false, closeButton: true)
        } else {
            updateView(header: "Unknown request", status: validatedResponse.url.absoluteString, animating: false, closeButton: true)
        }
    }
    
    // Complete account linking
    private func usingAuthCodeToGetAccessToken(amazonAuthCode: String) {
        guard let session = LocalSessionManager.loadSession(), session.sessionValid  else {
            updateView(header: "Status", status: "User not login", animating: false, closeButton: true)
            return;
        }
        AlamofireHelper.completeAccountLinking(userAccessToken: LocalSessionManager.loadSession()!.accessToken, amazonAuthCode: amazonAuthCode, state: StateHelper.generateState(session: session)).responseJSON(queue: DispatchQueue.global(qos: .userInitiated), options: []) {
            response in
            if let status = response.response?.statusCode, 200..<300 ~= status {
                DispatchQueue.main.sync {
                    self.updateView(header: "Status", status: "Account Linking Succeed", animating: false, closeButton: true)
                }
                return
            } else {
                DispatchQueue.main.sync {
                    self.updateView(header: "Failed", status: "Account Linking failed", animating: false, closeButton: true)
                }
            }
        }
    }
}

// Open the account linking status page
let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "linkingStatusScreen") as! LinkingStatusViewController
initialViewController.response = validatedResponseself.window?.rootViewController = initialViewController
self.window?.makeKeyAndVisible()