User Journeys
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:https://<<PDA_NAME>>/#/hatlogin?name=<<APPLICATION_ID>>&redirect=<<REDIRECT>>&fallback=<<FALLBACK>>
Parameter | Meaning |
HAT_NAME | The (fully qualified domain) name of the DA owner, e.g. postman.hubat.net |
APPLICATION_ID | The id of your application that requests the application token, e.g. dataswift-sandbox |
REDIRECT | A URI to which the user will be redirected when the authorisation is completed successfully. It also contains the application token. |
FALLBACK | A URI which is being returned in case the authorisation failed |
In case of successful authorisation, you can find the application token in the
redirect as a query parameter named token.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
application id, redirect and fallback.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.:dataswift-sandbox://apphost?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:
{
"applicationVersion": "1.1.0",
"sub": "1-2W54A+zKlvs0AwL2nWUfMg4+t+ZtPTCksMhxH+fPTEII+muhk8lHEqu2bhEfhjlOlfGAwhxQHLO47/OaP2wVDBWpZzUnIZPAdLLvNJ+TVymLgw==",
"application": "developers-dev",
"iss": "postman.hubat.net",
"exp": 1574956077,
"iat": 1572364077,
"jti": "c72f17e77b12bd13a1c5faed19079ebf1aa21b1741bb35d0286393b53941e1b024d2e3fcbc052320642c8d536da4ac2eb4613e9f3c62d0fb0d56c986b5a5f00ae01de3b5fba366df7092dfa79b6d7864f2aed7511897f2d33fc8fca6d2c20536d002019633d1c41c81c55027474e44e40dc91c9f6e16038109e050af1ccd9fc9"
}
The key parts of the Payload are:
- The
applicationVersionis the version of the app that generated the token - The
applicationis the application id that generated the token, it must match the application that requested the application token - The
iss(issuer) is the address of the PDA that has created the token and that you should be logging in - The
exp(expiry) Unix timestamp the token was created, defining whether the token is still valid - The
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
/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.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.
Last modified 7mo ago