Akamai Edge Connect

Get started building an application with Edge Connect.

The following sections will walk you through getting access to a configured  Edge Connect ecosystem, complete with a test JSON Web Token (JWT) server, predefined access control lists (ACLs), and tools for managing and debugging connections. This ecosystem will enable you to get started building an application.

To begin, you’ll first need access to a configured message broker. The fastest and easiest way to get access to a configured Edge Connect message broker is by getting a 30-day Akamai developer account and sandbox. This sandbox provides you with access to the message broker; a JWT server with five users; and a portal for managing the users, generating JWT, and monitoring (or debugging) connections. The configuration of the broker is designed to work with sample clients available for download from our GitHub repository.

Note: To get your Akamai developer account and sandbox, you don’t need an Edge Connect contract, Pulsar credentials, or even be an existing Akamai customer. Simply follow the steps below.

Step 1: Register for an account

Go to the Edge Connect portal, fill out the registration info, accept the terms, and select “Register.” Within a few minutes, you’ll receive an email with a link that activates your account. You can then log into your account.

Step 2: Request a sandbox

Log into your account by going to the Edge Connect home screen, then select “sign in” and enter your email address and password from Step 1. Once authenticated, you’ll be taken to the developer dashboard. Select the “Request sandbox” button.

Once your sandbox has been approved and configured, you’ll receive an email containing three items:

  • Connection information
  • A server certificate to be used to validate the server on connection
  • A configuration file

Note: There may be a delay in getting your sandbox configured; if so, you will receive an email within two business days informing you on when you can expect your sandbox.

Once you receive your sandbox, you’ll have 30 days to test out the Edge Connect experience.

Step 3: Get to know your sandbox

Your sandbox will include:

  • The hostname to use for connections
  • A topic prefix (all topics accessed by users must start with the specified topic prefix)
  • A client-ID prefix (all client-IDs presented to the JWT server must start with that client-ID prefix to be authorized)
  • A list of usernames
  • A file containing the certificate to use during the TLS handshake to verify the server
  • A configuration file which has the hostname, topic prefix, and client-ID prefix (this file is a shortcut for configuring any downloaded samples)

Your sandbox will be configured with the five topic access control lists (ACLs) shown below; the first ACL provides a general place for publishing and subscribing, and the next four ACLs provide for user-based topics:

  • <topic-prefix>/data/# [<pub>] [<sub>]
  • <topic-prefix>/user/%u/pub [*] [ ]
  • <topic-prefix>/user/+/pub [ ] [<user-sub>]
  • <topic-prefix>/user/%u/sub [ ][*]
  • <topic-prefix>/user/+/sub [<user-pub>][ ]

Each sandbox comes configured with five users. All five users will have the <pub> and <sub> authorization groups. The fifth user will also have the <user-pub> and <user-sub> authorization groups. This means that all of the users can publish and subscribe to any topic that starts with <topic-prefix>/data/; additionally, that they can all write to their own user-publish topic, <topic-prefix>/user/<user>/pub, and subscribe to <topic-prefix>/<user>/sub. Finally, the fifth user can publish to any of the user sub topics and subscribe to any user pub topics. For more information about authentication, authorization, and ACLs, see Authentication and Authorization for the Internet of Things.

Step 4: Configure your sandbox passwords

Once you’ve received your sandbox, sign in to the portal and select “Manage sandbox”. You can now set passwords for the five usernames that have been configured. Once the passwords are set, those usernames will be available. You can use the configured JWT server to request login JWTs via an HTTP Post request, or you can generate a JWT token for a specific device in the portal.

Step 5: Test your usernames

You can use any REST API plug-in for your browser, or a simple CURL command, to test the usernames. You perform a simple POST to the domain specified in your welcome email.  A sample CURL command for testing usernames is shown here:
 

curl -X POST -H 'Content-type: application/json' --data '{"username":"<username>","password":"<password>","clientId":"<client-id-prefix><client-id-suffix>","expiry":"<option expiry yyyy-mm-ddThh:mm:ss.mmmZ>"}' https://<domain-name>/login
 

You get the username, client-ID-prefix, and domain-name from your sandbox (also included in your welcome email). The password is the password you set for the username in Step 4. The client-id-suffix is something you select to differentiate your devices.

Note: The client ID, prefix, and suffix must only contain valid characters a-zA-Z0-9-_ and must be less than or equal to 60 characters.

After processing the request, you should receive a response that looks like the following:

{"token":"<base-64-encoded JWT","message":"Successful authentication"}

This response shows that the username’s password has been verified. You can copy the token out of the response body and test it using jwt.io and you can see the JWT token broken out into the headers and claims.

Before building your application, set yourself up with any off-the-shelf MQTT-compliant utility that supports SNI. The MQTTfx tool, for example, will allow you to connect to your sandbox with a rich UI (be sure to use a valid, and not expired, JWT token in the password field). Once you’re set up with MQTTfx or something similar, you’re ready to start building your application.

Step 6: Build an MQTT-based application

Once your sandbox is ready, you can start building right away. There is a typical workflow when building an MQTT-based application when using JWT for authentication. The four-step workflow is as follows:

  • Log in: In order to get a proper JWT, a request needs to be made to the test JWT server. This is achieved by making an HTTP POST request to the sandbox’s hostname. If successful, a proper JWT is returned.
  • Connect: Connect to the MQTT broker using a standard SDK/client* on the same hostname on port 8883. This often requires making sure the server certificate matches the target server during the TLS handshake.
  • Publish and subscribe: Code up your application to do whatever you want.
  • Close: Close the MQTT connection.

*Akamai doesn’t require the use of a proprietary SDK, but there are some open source SDKs such as Paho clients that provide you with the necessary protocol support for various languages and operating systems.

If you’d like a quick start with Edge Connect, there are sample clients you can use in our GitHub repository. These sample clients are complete, and you’ll just need to configure them for individual sandboxes. This is where the configuration file that was described above in “Step 2: Get to know your sandbox” comes into play: that configuration file, when dropped into the correct location, will automatically configure the device code for the assigned sandbox.

The configuration file and the server’s certificate file are all that you’ll need to make the sample code connect. Each sample will have a readme file that indicates where to put these files and how to run the sample.