VOGO Voice – Knowledge Base

Account Linking and Auth

Estimated reading time: 5 min
In this article

Amazon AWS Cognito

Amazon Cognito lets you add user sign-up, sign-in, and access control to your voice app. This guide will walk you through the steps to setup your own Amazon Cognito account and link it to your voice app. It will also take you through the steps to create a simple interaction that will show how account linking can be used to protect user only sections of the app.

Cases when you would want to use an Identity-as-a-Service (IDaaS) platform is when you require a sign in system that will need to be used to restrict access to all or portions of your content within your voice app. It is also able to store name, email and other custom attributes that can also be used to drive decisions in how responses are made. These could be user id’s that are used in other databases to provide user specific interactions. If you need help on setting this up or want to learn more before getting started you can contact us at support@vogovoice.com.

Requirements before we begin

Getting Started

Before we can setup Account Linking in VOGO Voice we will need to create a User Pool in Cognito to store all of our username and passwords for our users. This will be the service that is used to authenticate the user.

  1. Begin by logging into to your AWS Management Console and navigate to Cognito Service
  2. Once you’re in Your User Pools, select Manage your user pools, Create a User Pool, or select the user pool that will be used
  3. Navigate to Attributes under the General Settings in the left hand side
    1. Select “Email address or phone number”
      1. Select the “Allow email addresses”
      2. If you want users to register with other fields, you may select those in the “Which standard attributes are required?” or add a custom attribute at the bottom. (This is not recommended.)
  4. Navigate to Policies under the General Settings
    1. Set your password strength
      1. Recommend minimum length 8+, numbers, lowercase, uppercase, and special characters
    2. Allow users to sign themselves up if you want users to have the ability to create accounts when linking an account
    3. Unless you have a specific reason to do so, leave the “Days to expire” at the default
  5. Navigate to MFA and Verification
    1. Don’t enable Multi-Factor Authentication unless necessary
    2. Select Email for “Which attributes do you want to verify”
  6. Navigate to App Clients
    1. Click Add another app client or update an existing one
    2. Name the App Client to be descriptive of the application
    3. Remember the App Client ID, it will be used later in your Manager Account when configuring account linking
    4. Select the config to use the App Client Secret, this will also be needed later for the account linking
    5. Save App Client changes
  7. Navigate the to App Client Settings under the App Integration section
    1. Check “Select all” in Enable Identity Providers
    2. Check “Cognito User Pool”
    3. The Callback URL(s) will be filled out later when we fill in the Account Linking in the Management System
    4. Check the “Authorization Code Grant”, “Implicit Grant”
    5. Check the Allowed OAuth Scopes you intend to use
      1. We recommend “email”, “phone”, “profile”, and “openid”
  8. Navigate to the Domain Name, fill out the “Domain Prefix”. Make sure to make it descriptive of the application. It’ll look similar to https://<name>.auth.us-east-1.amazoncognito.com for the account linking
  9. Navigate to UI Customization to add a logo, or other styling pieces for your OAuth

Configure VOGO Voice Account Linking

Now that we have Amazon Cognito setup we can switch over to VOGO Voice and update our skill to connect to this identify service. Once we have done that we will conclude but building a simple test interaction to verify all is working.

  1. Now we’re going to start filling out the Account Linking information. Open a new window or tab to the VOGO Voice Management Console (account.vogovoice.com)
  2. Navigate to the Settings > Account Linking
  3. Check the “Do you allow users to link an account with you” in order to allow Account Linking
  4. Check “Enable Skill without Account Linking” if you want users to be able to use the skill without needing to link an account
  5. Select the Type drop-down menu and select Auth Code Grant
    1. Implicit Grants are used by public clients where the access token is returned without an extra authorization code exchange step
    2. Authorization Code Grants are used by confidential and public clients and exchange an authorization code for an access token; it’s more secure
  6. Fill out the Authorization URL
  7. Have the AWS Console and the VOGO Voice Console next to each other
    1. <Domain>/oauth2/authorize?response_type=code&client_id=<App Client ID>&redirect_uri=<Redirect URI>&state=STATE
    2. Example: https://cognito-test.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=<APP>&redirect_uri=https://pitangui.amazon.com/api/skill/link/M21LPWOLISOC7Y&state=STATE
    3. Copy the Amazon Cognito Domain from the App Integration > Domain Name section of the AWS Console
    4. The Redirect URI will be located at the bottom of the VOGO Voice Console, use the first one that starts with “https://pitangui.amazon/”
    5. Copy and paste the App Client ID from under the App Clients into the appropriate area of the URL
  8. Skip the Domain
  9. Copy that same App Client ID from the AWS Console into the Client ID in VOGO Voice Console
  10. Add the Scopes that you set in the App Integration > App Client Settings in the AWS Console
  11. Fill out the following in the same style as the Authorization URL for the Access Token URL
    1. <Domain>/oauth2/token?state=STATE
    2. Example: https://cognito-test.auth.us-east-1.amazoncognito.com/oauth2/token?state=STATE
  12. Copy and paste the App Client Secret from App Clients in the AWS Console into the Client Secret Key in the VOGO Voice Console
  13. Drop down the Access Token Scheme and select Credentials in Request Body
  14. You can fill out the Default Token Expiration but it defaults to 3500
  15. Fill in the User Info Endpoint using the same domain URL as used for the Authorization URL, and Token URL
    1. <Domain>/oauth2/userInfo
    2. Example: https://cognito-test.auth.us-east-1.amazoncognito.com/oauth2/userInfo
  16. Click the Upload Account Link
  17. Now Link your account, you can do this by opening your Alexa App and heading to your skill and click Settings
  18. It should prompt you for your Cognito Credentials
  19. Congrats!! You’re all done!!

Testing Your Authentication

Now that you have everything setup and working, it’s time to try this out on your skill. To get started we will make a interaction that will require the user to link their account before getting an answer to their question.

  1. Go to the interactions buttons on the left then create a new interaction
  2. Drag-n-Drop the Link Account component
  3. Fill in a specified message for your account linking
  4. If the request has been granted, drag-n-drop an Add Variables component
    1. Drag-n-Drop the getOauthUserInfo function location in Data > Functions > Ajax
    2. Name the variable to use it in the response
    3. Example: [ test | getOauthUserInfo | Function ]
  5. Now you can reference the variable {{var.test}}
    1. If the variable returns an object of multiple key-value pairs, you may reference them accordingly.
    2. The object would contain scopes and whatever other associated data is returned through the client app
    3. Some apps may just return the single string scope. i.e., `email@gmail.com` instead of { email: ’email@gmail.com’, openid: ‘1234’}
  6. Now you can test your response by asking your Alexa device, or your Alexa App the interaction associated! Try it yourself!

Congratulations! You have complete your setup of Account Linking with Cognito. Check out our other articles on advanced use cases.

Retrieving User Information with the Token

  • Now you can use the domain to access user information based on the scopes.
  • GET Request
    • https://vogovoice-test.auth.us-east-1.amazoncognito.com/oauth2/userInfo
    • <DOMAIN>/oauth2/userInfo
  • Response
    {
    "sub": "0370ca6e-c9bf-4b2d-a7d6-f69c236da93b",
    "email_verified": "true",
    "email": "ckazakov@xentity.com",
    "username": "0370ca6e-c9bf-4b2d-a7d6-f69c236da93b"
    }

O Auth Account Linking

VOGO Voice has created their own account linking O Auth Server to be able to use user information in order to respond to interactions using that information. This server can pass back email, phone, address, truck numbers, client ID’s and more to be used in continuing interactions for the more accurate and up-to-date information. The interactions can use this information to query databases, look up other information pertaining to the user and much more.

  1. Log into your VOGO Voice management account
  2. Navigate to Settings -> Account Linking
  3. Check the ‘Do you allow users to link an account with you’
  4. Select the type to be Auth Code Grant
  5. Fill the Authorization URL with https://office.vogovoice.com/oauth/oauth/authorize
  6. Domains aren’t required at the moment
  7. Fill the Client ID with MocB8EQu9Ef0llVKPhVpUUwkuXJsZa1KQ2w4nj51wR4CB4+yTpichUOdV5ufSIY1ZwnLG4gkQCyulJoFuJ48sQ==
  8. Scopes are specific per client
  9. Fill the Access Token URL with https://office.vogovoice.com/oauth/oauth/token
  10. Fill in the Client Secret Key with AVuzk7BGxSDOBeiSu15Z6P8vxS346TTUwNh3pakeDkgS/9ukqnJGDHBoHJYhyN3XAFW3MoVyuyolOLrvD5Q+82qAHU/exJSuVblj+Mdu3PcZC48AW3jnDRZ4b/6AP9kvLJJwLHe5SqQbjUp/3YY0GnCTjuMD+0xFkBUyyZMsmAL0+AlA9HiVHaBwkhQ4RodnebCOdg5Ov6E3cX5ogn5HDTY6H3J01mX1Wgfewa9Dponpw4Sg9eiqLJf3Vs70BQKfYnzB1RuVQdjleD3I4UGH3L48tnSOn9zfE+cBrY/q5Jk6xDxWoV5iZPN+UQDjPOl6avDRBrZ9p37EYP0d5ZCUQg==
  11. Select the Access Token Scheme to be HTTP Basic (Recommended)
  12. The Default Token Expiration is 3600 ms. This can be changed based on the O Auth server specs for each client.
  13. If there is an User Info Endpoint, you can fill that out
    1. Usually, the URL will match the base URL for the token and authorization
    2. I.e. https://office.vogovoice.com/oauth/user_info
  • Finally, link your account by clicking on the Upload Account Link button located at the top of the page. Congratulations! You’ve successfully linked your account!
Was this article helpful?
Dislike 0

Related articles