The user journey is formed by a standard OAuth process. There are 3 steps involved:
- Send user to PDA login
- User enters password
- Receive application token via a callback
To redirect the user to the login webpage, it's vital to have user's PDA address, eg.
postman.hubat.net. Having that, the following redirect has to be executed:
The (fully qualified domain) name of the DA owner, e.g. postman.hubat.net
The id of your application that requests the application token, e.g. dataswift-sandbox
A URI to which the user will be redirected when the authorisation is completed successfully. It also contains the application token.
A URI which is being returned in case the authorisation failed
In case of successful authorisation, you can find the application token in the
redirectas a query parameter named
Upon redirecting, users will see a familiar "enter your password" screen, served by their own PDA:
Note the complete address is served via SSL, contains the name of the PDA as well as the
If the user logs in, they get redirected to the URL provided, with
tokenquery parameter appended and containing a RS256-signed JWT token, e.g.:
The token decodes to:
The key parts of the Payload are:
applicationVersionis the version of the app that generated the token
applicationis the application id that generated the token, it must match the application that requested the application token
iss(issuer) is the address of the PDA that has created the token and that you should be logging in
exp(expiry) Unix timestamp the token was created, defining whether the token is still valid
iat(issued at time) Unix timestamp the token was issued, used to calculate if 30 days have lapsed since the time the token was first issued
You can verify the signature of the token, which is generated from the token and the private key of the PDA, by accessing the
/publickeyendpoint 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.
Signature validation is useful in case you need to verify that the token has not been tampered with in any way.
A few useful resources to help you with JWT tokens:
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 that the library of your choice is up to date and does not have reported security flaws.