User Journeys

User journey
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
Send users to the PDA login
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.
User enters password
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.
Verify and authenticate user
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 applicationVersion is the version of the app that generated the token
The application is 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.

6. CRUD Operations

User Onboarding

Last modified 3mo ago

Copy link

Outline

User journey

Send users to the PDA login

User enters password

Verify and authenticate user