1. Authentication
Last updated
Last updated
HAT-API-Android provides features that enable your app to authenticate with the PDA, read/write to the PDA, fetch and setup Data Plugs and Applications, fetch Data debits and use advanced features like Combinators and Bundles.
The PDA is an API-only service, meaning it does not enforce a specific Application or User Interface to expose the data to the user. Instead, authentication happens using the HAT APIs and the Javascript Web Token (JWT). Each PDA runs as a separate server and has a publicly reachable address (such as https://postman.hubat.net). All calls in this documentation are therefore executed against an individual PDA.
The steps to logging in with a PDA are:
You send the user to /hatlogin endpoint on their PDA, such as https://postman.hubat.net.
The PDA owner enters their login details in the login screen and verifies the service they are logging into.
The user is redirected back to the address you have provided with authentication token in a query parameter. You validate the token against the PDA’s public key to confirm that the user owns the specific PDA and log them in.
To log in the user with their PDA, you need to ask for their PDA address. Depending on the status of your app within the HAT ecosystem you may also have a specific application name, an allowed success redirect url and an allowed fallback redirect url to which the user is sent to complete authentication. If you do not have these details, you can put any application name, success redirect url and fallback redirect url. However, the authentication token you receive will not grant you any permissions to do any operations on the PDA; it can only verify that the token really came from the PDA.
For an Android application that means asking user to type the DA Address. Here's a very simple example:
In the above image, the user is being asked to fill in the HAT address, postman, and select a domain, .hubat.net. There can be other domains as well, e.g.: hubofallthings.net. We thought that splitting the address and the domain made for a better UX, but this is not a requirement for your app. You could have one EditText that the user will have to type the full address, postman.hubat.net.
Having asked the user to fill in the DA address, e.g. postman.hubat.net, you have to send them to "https://$hatAddress/#/hatlogin?name=$applicationName&redirect=$redirectURL&fallback=$fallbackRedirectURL" endpoint of the PDA, where:
$hatAddress is the PDA's (fully qualified domain) address, e.g. postman.hubat.net
$applicationName is the name of your application on the HAT. This is defined once when you complete the form to create a new application. e.g testing
$redirectURL is the URL to which the user should be sent after completing authentication. Optional. For an Androidapplication that would probably be: $applicationName://success and has to be added in the AndroidManifest.xml file of
the project in intent-filter of an Activity as a data with host="success" and scheme="$applicationName".
$fallbackRedirectURL is the URL to which the user should be sent in case the authentication has failed. Optional.
For an Android application that would probably be: $applicationName://failed and has to be added in the AndroidManifest.xmlfile of the project in intent-filter of an Activity as a data with host="failed" and scheme="$applicationName"
In an Android application, in order to redirect the user to an existing DA address and proceed to the next step, we have to use WebView to open the URL.
To achieve this with WebView you have to create an xml file with WebView element and an activity with the login address described above, "https://$hatAddress/#/hatlogin?name=$applicationName&redirect=$redirectURL&fallback=$fallbackRedirectURL", and then via a Activity, present the WebView layout. e.g.:
That will launch WebView within the app and load the url specified.
In the next step, users will be asked to fill in the password for the particular PDA Address:
This screen cannot be modified in any way. Users have to insert the password for the specified PDA and tap LOGIN.
Note that the complete address is served via SSL, contains the PDA's name as well as the application parameters – application name, redirect url and fallback redirect url.
By tapping LOGIN the authentication process will begin. PDA will use one of the two redirect url that were included in the request; success redirect if everything went ok or fallbackRedirectURL if an error occurred. The application has to know how to respond in both scenarios.
To achieve that, we have to add the success redirect and fallbackRedirectURL to the AndroidManifest file in the project.
To add them to the AndroidManifest file, you have to add the Key URL Types as a data.
This will be your app's url scheme. That means every time Android intercepts a URL starting with this value, like test://host will hand the process to your app, which will be responsible to either launch or not.
If the user logs in, they get redirected to the URL provided, with token query parameter appended and containing a RS256-signed JWT token, e.g.:
The token will decode to something like this:
The Header:
The Payload:
The key parts of the Payload are:
The applicationVersion, the version of the app on HAT
The sub (subject), the subject of the token
The application, the application name that requested the token
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 iat (issued at time) time that the token has been created as a Unix timestamp, defining whether the token is still valid. Token expires after 30 days of the issued at date, no matter if a refreshed token has been received from PDA.
The jti (JWT ID) the ID of the token
The Signature, which is generated from the token and the private key of the PDA. The signature must be verified to verify that the token has not been tampered with. A PDA’s public key 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 that you can use in your project.
When you have received a successful redirect from PDA, you can check with HAT API Android and verity the user. To do so you simply have to call:
applicationName is the name of the application that sent the user to log in
url is the full url that returned from the PDA, like the example at the beginning of step 3.
success is a callback to execute when the library has successfully authorised the user. You can use this callback to dismiss WebView activity, save the values needed and navigate to the next Activity.
failed is a callback to execute when the library couldn't authorise the user. You can use this callback to dismiss WebViewactivity and show an error message to the user.
Having received the success callback you have to save the token, ALWAYS use Encryption to save the token. DO NOT save it in any non-encrypted database. It's also a good idea to save the full PDA Address, as you will need it many times to communicate with the PDA. You can store the values in SharedPreferences in Private mode.
As soon as you save the token you are free to navigate to your next Activity.
If the authentication fails, you will be redirected to the fallback url. In that case you should dismiss WebView Activity and then update the UI or show an error message back to the user.
You can dismiss the browser from the viewController that presented originally the Activity, like this:
