IHAN® Developer documentation


« Back to index


Authentication API

SisuID authentication API supports the OpenID Connect protocol

SisuID will be integrated with the Service Provider as an external authentication method. The type of the authentication method will be set to OIDC. SSN or SisuUUID information returned by SisuID in the ID Token claims will be used to map to existing users in the Service Provider's local user directory.

Request flow

  1. End-user initiates the flow by accessing a protected resource in the Web App.
  2. Web App notices that the user has not authenticated and construct redirection URL to the Service Provider's local access management endpoint.
  3. End-user's web browser sends an HTTP GET request to the Service Provider's access management endpoint with entityId uniquely identifying the Web App. and scope indicating that the access management end-point should return the user information of the authenticated user.
  4. Since it is assumed that SisuID external authentication method is being used, the access management end-point constructs redirection URL to the SisuID authorization endpoint.
  5. End-user's browser sends an HTTP GET request to the SisuID authorization endpoint with following paramters:

    • client_id uniquely identifying the Web App.
    • acr_values indicates that mobileauth authentication method is used
    • scope indicates that basic OpenID Connect id_token information needs to be returned and that it needs to contain the user attributes of the basic profile and the linked government issued IDs
    • redirect_uri points to the Service Provider's redirection endpoint
  6. SisuID authenticates the end-user and redirects back to Service Provider redirection endpoint with code and state parameters.
  7. End-user's browser send an HTTP GET request to the Service Provider redirect URI.
  8. Service Provider resolves the access token and ID token associated to the provided authorization code by making a call to the SisuID token endpoint.
  9. SisuID returns the access_token and id_token. The id_token contains the Social Security Number (SSN) or SisuUUID of the authenticated user in the claim.
  10. Service Provider uses its user directory mapping to perform a lookup to its internal user repository to determine whether an existing user is found with the given SSN or SisuUUID. If no user is found, an error is returned to the Web App.
  11. If a user is found, new local authentication session is created for that user.
  12. Finally after successful authentication, end-user's browser is redirected to the Web app ACS url which was provided in step 3. The final steps of the flow are omitted from this document.
© 2020, IHAN® Project