Application Management

Overview

An Application on the PDA is represented with a comprehensive structure encoding all key aspects of its interaction with the PDA and the owner. It includes:

  • A unique identifier

  • The kind of an app, such as a mobile application, a Data Plug or a tool internal to the PDA

  • High-level information, including description and the various graphics, such as the logo and demo screenshots

  • Permissions — the level of access the app should have within a PDA when authenticated

  • Setup process, defining the steps of setting up the application with a PDA

  • Status check process, defining the procedure of checking if the application is active

It is easier to illustrate the different aspects with specific examples:

  • Facebook Data Plug in the above would be of type Data Plug and include information such as version, name, textual description, potentially with no screenshots as plugs typically do not have a user interface. To give a PDA owner an idea of what data it pulls in, it would include a "data preview" with some sample data. Permissions would say that the application has rights to write to the facebook namespace on the PDA, but does not read any data and has no Data Debit associated. When setting up any Data Plug the owner typically needs to authorize data fetching with the source (Facebook), therefore it needs an External setup, indicating the address to redirect user to. Finally, data fetching authorization can be disabled at the source, therefore to make sure that a plug is still active, an External status check is needed.

  • Notables app would be of type Application with platform set to iOS and list information similar to Data Plugs, but screenshots should also be provided. Notables is an example of where the service consists of a user application as well as a backend service handling requests to share notables on social media as well as take them down. It therefore needs permissions to 1) write data to rumpel namespace, where notables are stored, 2) read data from rumpel namespace to render all notables as well as owner's profile information, 3) set up data plugs and 4) associated data debit, which allows backend service to access shared notables. Setup in this case is also external — PDA owner needs to be redirected to the Notables application. The URL the owner gets redirected to include access token as a query parameter. Finally, external status check ensures that the backend can periodically get a new access token to fetch data from the PDA.

  • Rumpel as an "Owner" application — details include similar level of information as Notables, however it requires "Owner" level permissions. Since owner applications should not be sending data to external services, status check is also "Internal" and only checks if the application is enabled.

Reference

Application

Property

Type

Description

id

String

unique application identifier

kind

ApplicationKind

defines the kind of an application, potentially changing some of the application aspects below

info

ApplicationInfo

defines user-readable information about the app

permissions

ApplicationPermissions

defines what the application can do, in the form of roles granted and/or data debit requested

setup

ApplicationSetup

how does one start using the app?

status

ApplicationStatus

how does the PDA reports if the app is active

ApplicationKind

Defines the kind of an application, potentially changing the application behaviour

Property

Type

Description

kind

String (App, Data Plug or Tool)

defines the kind of an application, potentially changing some of the application aspects below. Options include: App — a full, external application that uses HAT as a backend Data Plug — a Data Plug that pulls data in from a remote source on behalf of the user Tool — a tool that has UI integrated within a PDA application, but may need to rely on a separate backend service for processing data

url

String

URL where general information about the application can be found

iosUrl

String, Optional

URL where iOS-specific information about the application can be found, e.g. the Application's App Store page

androidUrl

String, Optional

URL where Android-specific information about the application can be found

ApplicationInfo

Defines user-readable information about the app

Property

Type

Description

version

String

uses three-number, dot-separated versioning in the spirit of semantic versioning to track changes to application requirements and allow to signal backward-compatibility or required updates as the application evolves

published

Boolean

Boolean flag indicating whether this version if the application has been published

name

String

human-readable name of the application

headline

String

one sentence description of what the application does

description

FormattedText

formatted text (currently plaintext and optionally Markdown and HTML) with full details of the application

dataPreview

List of DataFeedItem

a sequence of items main data feed structure, to show a generic preview of what data created by the application on the HAT will include

graphics

ApplicationGraphics

graphical elements to build the UI from, primarily images. Each follows the format of a “Drawable” object, which has a url to the “normal” size image as well as optional ones sized as small, large and extra-large, targeting different screen sizes

FormattedText

Provides text formatted for the various formats used: plaintext, markdown, html...

Property

Type

Description

text

String

Plaintext (unformatted) text

markdown

String, Optional

Markdown-formatted text

html

String, Optional

HTML-formatted text

ApplicationGraphics

Graphical elements to build the UI from, primarily images. Each follows the format of a “Drawable” object, which has a url to the “normal” size image as well as optional ones sized as small, large and extra-large, targeting different screen sizes.

Property

Type

Description

banner

Drawable

Banner image to be shown in application listing

logo

Drawable

Logo of the app

screenshots

List of Drawable

A list of screenshots demoing the application

Drawable

Property

Type

Description

normal

URL (String)

URL to a normal-size (default) graphic element to use

small

URL (String), Optional

URL to a small-size graphic element to use, targeted at small screens (less than 576px)

large

URL (String), Optional

URL to a large graphic element to use, targeted at large screens (above 992px)

xlarge

URL (String), Optional

URL to an extra-large graphic element to use, targeted at largest screens (above 1200px)

ApplicationPermissions

Defines what the application can do, in the form of roles granted and/or data debit requested

Property

Type

Description

rolesGranted

List of UserRole

a list of roles granted for the application (/the PDA owner using the application), such as “Owner” or “DataDebit”. Although it would be the owner user in majority of cases when using those apps, they all have limited permissions depending on what has been approved

dataRequired

DataDebitRequest, Optional

a data debit request information for the application when it operates as a “Data Acquirer” and downloads the data somewhere else (e.g. Notables backend service). Such Data Debits always have an ID of "app-"

ApplicationSetup

Setup process — how does one start using the app?

Property

Type

Description

kind

String

the kind of application setup: Internal or External

onboarding

List of OnboardingStep, Optional

a few onboarding steps with simple heading, illustration, text, to explain to the user what the application does and how it interacts with them

preferences

ApplicationPreferences

a list of preferences, with default values

url/iosUrl/androidUrl

URL (String), Optional

identifying the setup URL for the different platforms available

The main difference between Internal and External is that Internal setup happens without leaving the app, where all controls are presented in the controlling UI, while External is an external process, where the user is sent off to another interface to set up. In both cases, “Permissions” needs an explicit approval step.

ApplicationStatus

Status check process — how does the HAT reports if the app is active.

Property

Type

Description

kind

String

the kind of application status check: Internal or External

compatibility

Version

indicates the lowest version number this version is compatible with, primarily — in case of permission changes

recentDataCheckEndpoint

HAT Data Endpoint (String), Optional

which PDA data endpoint to check for the most recent timestamp of data saved, e.g. to see that the application has recently been active

statusUrl

URL (String), Set when kind=External

identifying the status check URL. The URL is called with x-auth-token encoding user's token in a header

expectedStatus

HTTP Status code (Numeric), Set when kind=External

identifying the expected status code in response to status check request

In both cases, HAT has the responsibility of checking:

  • if the application has been enabled

  • if the currently set up version is compatible with the one available publicly

  • timestamp of the most recent data available, if the setting is included

  • whether the Data Debit has been setup, enabled and matches the currently required one

  • making an authenticated call to statusUrl, checking the status reported by the remote system

Integration & Authentication Scenarios

If you develop an application on Dataswift's PDA, you will register your application with DEX, for it to provide all the necessary details to PDAs.

Once registered, all PDA owners will be able to discover your application and start using it. If the application setup is "Internal", the user won't be redirected to your application from the Application setup flow, however for an app that is set to do an "External" status check, you will still receive a status check request with the HAT user's token. If, on the other hand, application setup is "External", HAT will redirect the user to your application, with associated token as a parameter.

Overall, you have three cases to handle:

  1. User comes to you directly and you would like to log them in via their PDA

  2. User comes to you from their PDA with an authentication token

  3. Communication is handled in backend between Dataswift's HAT and your backend

User comes to you

To log the user in with their PDA, you need to ask for their PDA address. Depending on the status of your app within the Dataswift's HAT ecosystem you may also have a specific application name and an allowed redirect url for the user to be sent to complete authentication. If you do not have these details, you can put any application name and redirect url. The authentication token you will receive from the HAT will reflect the settings in the Application manifest. Your own application is tasked with choosing the correct redirect url if the url varies across different platforms.

To log the user in, you therefore send them to https://<<HAT_NAME>>/hatlogin?name=<<APPLICATION_NAME>>&redirect=<<REDIRECT_URL>> endpoint of the PDA, where:

  • <<HAT_NAME>> is the (fully qualified domain) user's PDA name

  • <<APPLICATION_NAME>> is the name of your application as explained above

  • <<REDIRECT_URL>> is the URL where the usr should be sent for completing authentication

If you redirect the user to an existing PDA, they will be asked to login through an interface they are familiar with:

After logging in they will be asked to approve application permissions (if not yet active).

Note the login page is served via SSL and includes the complete address, name of the PDA as well as the application parameters — name and redirect url.

User comes from Dataswift's HAT

If the user approves application permissions, they get redirected to the URL provided, with token query parameter appended and containing a RS256-signed JWT token, e.g.:

https://twitter-plug.hubofallthings.com/authenticate/hat?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJleUp3Y205MmFXUmxja2xFSWpvaVkzSmxaR1Z1ZEdsaGJITWlMQ0p3Y205MmFXUmxja3RsZVNJNkluUmxjM1FpZlE9PSIsInJlc291cmNlIjoiaHR0cHM6XC9cL3R3aXR0ZXItcGx1Zy5odWJvZmFsbHRoaW5ncy5jb21cL2F1dGhlbnRpY2F0ZVwvaGF0IiwiYWNjZXNzU2NvcGUiOiJ2YWxpZGF0ZSIsImlzcyI6InRlc3QuaHVib2ZhbGx0aGluZ3MubmV0IiwiZXhwIjoxNDk2OTIyNDIxLCJpYXQiOjE0OTY2NjMyMjEsImp0aSI6ImJlMGYyOTY3Nzk3MDc5MThkOWEzZDYxOGRkOTg5MGQ2MDRkMGRlMTg2MDEzYjE2MTYwNmU5ZmVmZDgxYmRjMmJjZTVjZDE2NWE2MTAxZWU0ZTU1NzJiYmVkMjIzYTRmOWRiNDcyNDc5YTBhMDY4ODkwNGZhN2QxZTUxNThjMzJlMzNhOTY5YWRmZTdkYzc4MmI4ODk1ZjJhY2E2MDMyOTM3NTRmZWJhNGUxNzNhMzE3ZmQ3ZDk1OTQyYzRmNTRkMWM3YWM5YzI3OThiYTZhODZhZWEzYTBmMzQ4OTI4MDJlZDQ4ZmU1NWEwMmUyYjgzNDJlODUxM2E2MTEzODBmYWIifQ.4thestm60WrueQmlBxDRp37uGKUtGpx6PeE4lB_xzlRmxrQ67vk1xFT1nyvFvZfGLnkq51GaB5UsA_zbMhhATC8dDWX1FjNiiRfjAj5r5LFTZW-hRnI0LodzyEJ8YMFbG_t-epSo_KsIig4Ardnzt5VioLwmdr37YJLHxmn1033ArBocVqsAg_pH8DghsaRbzdDWXHcwnCO5wtHJn0RVvAdXG5TKhegs3AuneYktTktvYjj__o66kn8DROKsqeICqCAJTxuJFQpBdoOlPXGgfUW4VQ1wcFC91MoPns1I04otuo6wglCXE576NnLHL3Q7ZKZ_CTVqmnlNg5txC_pnog

The token decodes to:

The Header:

{
"typ": "JWT",
"alg": "RS256"
}

The Payload:

{
"sub": "eyJwcm92aWRlcklEIjoiY3JlZGVudGlhbHMiLCJwcm92aWRlcktleSI6InRlc3QifQ==",
"resource": "https://twitter-plug.hubofallthings.com/authenticate/hat",
"accessScope": "validate",
"iss": "postman.hubat.net",
"exp": 1496922421,
"iat": 1496663221,
"jti": "be0f296779707918d9a3d618dd9890d604d0de186013b161606e9fefd81bdc2bce5cd165a6101ee4e5572bbed223a4f9db472479a0a0688904fa7d1e5158c32e33a969adfe7dc782b8895f2aca603293754feba4e173a317fd7d95942c4f54d1c7ac9c2798ba6a86aea3a0f34892802ed48fe55a02e2b8342e8513a611380fab"
}

The key parts of the Payload are:

  • The resource, which you must verify to check the token was intended for your service

  • The iss (issuer), which is the address of the PDA that has created the token and that you should be logging in

  • The exp (expiry) time of the token as a Unix timestamp, defining whether the token is still valid

  • The application which defines the rights of the token — application would not get permissions higher than pre-approved

    ones even though it (indirectly) uses PDA owner credentials.

And the Signature, which is generated from the token and the private key of the PDA. The signature must be validated to ensure that the token has not been tampered with. The public key of a PDA can be accessed at the /publickey endpoint of the PDA (e.g. https://postman.hubat.net/publickey). The precise handling of tokens with asymmetric keys will depend on your library, however you need to make sure that your library supports RS256 keys.

jwt.io contains a very useful tool for token debugging while in development as well as listing all the major JWT libraries.

JWT libraries are available in all major programming languages and most major frameworks implement wrappers for them. You should be careful in verifying the library of your choice is up to date and does not have reported security flaws in it.

Backend communication

When communication happens between HAT and your backend, specifically when "External" status check gets executed. The check is equivalent to:

curl -X GET \
<<STATUS_URL>> \
-H 'x-auth-token: ACCESS_TOKEN'

In this case the token would be the same as explained above and your application is expected to store the token for future interaction with this specific user's PDA.

All PDA application management is performed through the endpoints to list, setup and disable the apps as well as in certain cases — get the application token for the frontend to use in authenticating with a remote service.

Application Management

Listing applications

Applications are listed at /api/v2.6/applications — returns the full list of approved applications

This method is the only one needed to call to get a comprehensive list of applications along with their status on the HAT:

  1. Fetches all available applications from the “Trusted Application Provider” (normally DEX)

  2. Fetches the list of applications set up on the Dataswift's PDA

  3. For each application that has been set up, executes a status check as indicated in the detailed structure description: 1. Checks if set-up application version number is compatible with the current one 2. Fetches timestamp of the most recent data if the setting is present 3. For Internal status checks, checks if the required data debit is setup and active, in which case the app is considered “active”.

    For External status checks, generates the corresponding application token and makes an API request to the configured endpoint internally,

    setting status to “active” if it receives expected status code

The resulting list contains for each application:

Property

Type

Description

application

Application

Application details

setup

Boolean

indicating whether the application has been setup

active

Boolean

indicating whether the application is active

needsUpdating

Boolean, Optional

indicating whether application needs to be updated by calling the “setup” endpoint again and asking the user to review any permission changes. Only present if the application has previously been setup

mostRecentData

Date, ISO-8601, Optional

timestamp of the most recent data record available in the configured endpoint

An individual application information is accessible at /api/v2.6/applications/:application-id but this shouldn’t be needed in most cases. It will have exactly the same information and format as a single item in the list returned by /api/v2.6/applications.

Setting up

Application is set up by calling GET /api/v2.6/applications/:application/setup

Most of the steps of setting up an application with a PDA happen transparently after calling the setup endpoint, for both Internal and External applications:

  • extracting the Data Debit request from the app definition, saving or updating the existing data debit as well as enabling it

  • updating the internally recorded status of the application, to mark it as setup and record version number setup

  • refreshing status of the application

It is up the UI to display the onboarding screens and collect user preferences. When the application is Internal, there is no further setup that should or could be carried out.

If, on the other hand, the application is External, configuration may include a default (web) url, an iOS-specific or an Android-specific url identifying the application to be launched. In this case the url is chosen by the UI depending on where it is running, i.e. an iOS application should not choose to redirect the user to an Android-specific url. To log the user in, they should then be redirected to /hatname/hatlogin?name=app-id&redirect=url.

Similarly, an application gets disabled by calling /api/v2.6/applications/:application/disable. This takes care of recording the fact on the PDA, disabling any data debits and stops tokens issued to that application from working with the PDA.

Obtaining application token

For some applications (services), especially those that have External setup flow, you may need the application’s token, which can be obtained by calling /api/v2.6/applications/:application/access-token. This endpoint is, however, very restricted and by default for any application, including those with “Owner” level access, will return Forbidden status.