Skip to main content

Integrating Hanko Identity

Connecting your app to Hanko Identity initially boils down to two processes: login and logout. You need to create separate endpoints for each process within your application that will handle the login and logout requests.

How to Login (or register)

  1. Have a dedicated login route, like /login for example. This route needs to make use of the OpenID Connect (OIDC) library of your choice - pick one from our list if you like. The job of this route is to check for a valid authenticated user session and redirect accordingly.
  2. Have this route check if the user has a valid authenticated session locally in your app. Just to make sure. If you have a "Login" button on a couple of pages of your app, you can store the originating page in the session to have it available after authentication.
  3. If the user does not have a valid authenticated session: redirect the user to Hanko Identity, using the OIDC lib, triggering "authentication".
  4. After authentication at Hanko Identity, the user will be redirected back to /login with a code.
  5. Provide this code to the OIDC lib, which in turn will exchange it for an ID token, an access token and possibly a refresh token at Hanko Identity. Your app does not need these tokens directly, only the OIDC lib does. Store them in your app's backend, a session would also be suitable for example. If you have a distributed app or if you load-balance across multiple instances, this session store needs to be accessible by all instances of your app.
  6. Store the user's details in your local session and consider the user logged in. The OIDC lib will provide you with all the user's details (like the user_id for example) from the ID token, so you can query your local user settings store with them.
  7. Now redirect the user to the page he/she was trying to access before authentication.

In case of a new user that has just registered at Hanko Identity (instead of just logging in), initiate onboarding within your app if applicable.

How to Logout

  1. Have a dedicated logout route, like /logout for example. Again, use the OIDC lib you have chosen above.
  2. Make sure this route is configured in Hanko Identity as Logout URL (see Configuration).
  3. Have this route check for a local user session and clear that session locally in your app.
  4. Redirect the user to Hanko Identity's logout endpoint /oauth/sessions/logout.
  5. Hanko Identity will close the user's session and redirect back to your /logout route.
  6. Now your /logout endpoint again checks for a local session, which has been cleared in step 3. So now it simply redirects the user back to the start page of your app for example.