Understanding Account Linking
Account Linking lets you securely grant skills (and other voice or conversational applications) access to personal data.
For example, you could develop an Amazon Alexa skill called Social Buzz that provides users with updates from your social network, such as Facebook. When a user asks Social Buzz, What’s happening now?, the skill responds by saying, Your friend Alice Smith recently said, "Any thoughts on the new Amazon Echo Show?”
The "Social Buzz" skill needs access to the user's social media data to provide a personalized experience. Amazon Alexa, Google Assistant, and others provide account linking so that users can grant voice skills, like Social Buzz, secure access to data from third-party services, like Facebook or Orbita.
For another example, you could develop a Google Assistant app called Sleep Journal that lets a user log the length and quality of a user’s sleep. When a user says, Hey Google, tell Sleep Journal I slept 8 hours last night, that information can be securely stored in Orbita, and associated with that user's information. Sleep Journal needs account linking to access and save the data in Orbita.
Orbita supports both scenarios, where account linking accesses data from a third-party service such as Facebook, and also where account linking accesses and manages data from Orbita.
Orbita supports account linking to any third-party system that supports the Auth Code Grant Flow of OAuth 2.
Authentication and Authorization
Account Linking uses authentication and authorization.
Authentication. Your identity, often from a username and password combination.
Authorization. When your identity is verified, you are authorized to access and modify the resources of the system.
OAuth
OAuth is an authorization framework specifically built for HTTP APIs that lets a user (such as Bob Smith) grant an application (such as an Alexa Skill) access to user data (such as Bob Smith’s data in Orbita).
There are four roles involved in an OAuth transaction.
Resource Owner. The end-user. (For example, Bob Smith.)
Client. The application that requests access to the resource owner’s data. (For example, Amazon Alexa Skill, Google Assistant Application, Web Chat Bot, and so on.)
Protected Resource. The protected HTTP API. (For example, Orbita REST API, Your Company's API, Facebook’s API, and so on.)
Authorization Server. The OAuth server that verifies identity (authentication) and determines what data can be accessed and modified (authorization).
Scenario 1. Account Linking with an Orbita User
In the example of Sleep Journal, the skill logs the length and quality of a user’s sleep. When a user says, Hey Google, tell Sleep Journal I slept 8 hours last night, that information is securely stored in Orbita, and associated with that user's information.
To do this, the following roles are established:
Resource Owner. Google skill user
Client. Google skill
Authorization Server. Orbita
Protected Resource. Orbita REST API
To enable authentication and authorization, when you create a new skill project in Orbita, specify the OAuth provider, which is set to Orbita by default. Any account linking offered through the skill to an end-user requires authentication using an Orbita username and password.
Scenario 2. Account Linking with a Third-Party System
Orbita can support account linking to any third-party system that supports the Auth Code Grant Flow of OAuth 2.
In this scenario, Acme, Inc. creates an Amazon Alexa skill to track and manage orders of medical supplies for a user. For example, a user might ask, Alexa, Ask Acme what's my order status?
The Amazon Alexa skill uses account linking to securely authenticate a user with a username and password from Acme, Inc., and authorize skill access to order data from Acme, Inc.
In this scenario, the following roles are established:
Resource Owner. Amazon Alexa skill user
Client. Amazon Alexa skill
Authorization Server. Acme, Inc
Protected Resource. Acme, Inc. Order REST API
First, configure the authorization server in Orbita.
Go to the global menu and select Providers. The Providers page appears.
Click Add (+). The Provider specification form appears.
Specify the following information:
Note: An OAuth provider’s system administrator must register the Amazon Alexa skill in the Authorization Server as a valid client. Inform the system administrator that you are setting up a “confidential Client Application" that uses the "Auth Code Grant Flow.” After the Amazon Alexa Skill is registered, some of the following information is provided by the system administrator.
Authorization URL. Defined by the OAuth provider’s system administrator, the Authorization URL is used in the first step of the flow to request authorization from the user.
Token URL. Defined by the OAuth provider’s system administrator, the client application requests an access token from the Authorization Provider using this URL.
Client ID, Client Secret. Issued by the service after your application is registered, "client credentials" are in the form of a client identifier and a client secret.
The Client ID is a publicly exposed string that is used by the service API to identify the application and is also used to build authorization URLs that are presented to users.
The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user's account and must be kept private between the application and the API.
Callback URL. The callback URL is the URL that the skill wants you to see after a transaction with the client. For example, if you place an online order, you likely have your purchase transaction handled by another client (such as PayPal). After the client processes your purchase, the client needs to return to a URL that your skill controls, depending on the type of client application you are building. Therefore, provide a callback URL to the OAuth provider’s system administrator. Contact https://orbita.help if you need assistance.
For example. http://<baseURI>/api/auth/amazon/callbackScope. Defined by the OAuth provider’s system administrator, this value determines the scope of data access the user can choose from.
Persona Type. When an account is linked, a placeholder user account is created in Orbita. The user is created using the persona type specified in the pull-down menu.
Profile Options. Profile Options will fetch and store the information of the logged-in user, from the client's database. A JSON code that contains the URL, header, method, body, attributes is to be used in this field to get the data.
URL. The Endpoint to get a user’s profile information.
header. If the header is needed for the request, it must include the header as key and value pair.
method. Http verb for profile URL request.
body. Used when a body for request profile is needed.
attributes. Attributes maps the "profile attributes key" with "id", "firstName", "lastName" of the client's attributes. We have limited the mapping to "id", "firstName", and "lastName" for now.
For example, if the profile attribute "id" has to be mapped with Client's "user_id", we have to use "attributes":{"id":"user_id"}
Sample format 1 of Profile Options:{ "url": "https://api.amazon.com/user/profile?access_token=__ACCESS_TOKEN__", "method": "GET", "attributes": { "id": "user_id", "firstName": "first_name", "lastName": "last_name" } }Sample format 2 of Profile Options:
{ "url": "https://www.yourdomain.com/userinfo", "method": "GET", "header": { "content-type": "application/json", "Authorization": "Bearer __ACCESS_TOKEN__" }, "attributes": { "id": "user_id", "firstName": "first_name", "lastName": "last_name" } }
When specifications are complete, your new Oauth Provider appears in the Select OAuth Provider drop-down list in your Add New Project (and Project Properties) dialog box.
