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.