Backend integration

Authentication

The application embedding the Saakuru Mobile SDK needs to provide an SSO endpoint for the SDK backend to verify user information. The response from the endpoint should be similar to Google’s ID token, such as sub, iat, exp, email, name, and aud.

{ "sub": "user ID", "iat": "issue time", "exp": "expiry time", "email": "user email", "name": "user name", "aud": "audience ID" }

  • sub is the user ID of the application. It should be unique and always the same.

  • iat and exp are the issue and expire time. The token is valid only within this timeframe. email is the email of the user.

  • name is an optional field. It is the name of the user.

  • aud is the audience ID. It is a predefined constant used to prevent the token issued to other applications being used to access data about the same user.

Both the audience ID and token info url will need to be provided for integration.

Sequence Diagram

  • The user logs in to the application and gets a token.

  • The token is passed to SDK ssoLogin API.

  • SDK verifies the user info by querying the SSO endpoint (tokenInfoURL).

  • Upon validation, a session is created for the application to use the SDK and its APIs.

Emails

The SDK is able to send the following system emails on behalf of the application using generic templates:

Customization to the email template, sender name, and sender address is possible.

Notifications

The application can receive various user events from the SDK by setting up a webhook. The application can push notifications to users based on the event type.

The event format includes fields such as user, title, body, and data.

{ "user": <user id, the sub value from SSO tokenInfoURL>, "title": , "body": , "data": }

Below is the list of event types, format details, and sample messages:

Considerations

Error Handling

  • Handle invalid token request, tokenInfoURL should return error and non 200 http status response.

  • Handle scenario where the user failed to reset the signature due to exceeding the limit of verification attempts. SDK will notify the application to log out of the user.

  • Handle max concurrent sessions and logout the user appropriately.

Security

  • Protect the tokenInfoURL endpoint and notification webhook by whitelisting the SDK server IPs or assigning API keys.

  • The token should be unique, generated by a non-deterministic algorithm, or digitally signed with a small window of the validation time period.

  • Monitor traffic to detect and then stop bot and malicious requests.

  • Always log out from the SDK when the user logs out from the application.

Session Management

  • A limit should be set for the maximum number of concurrent SDK sessions allowed.

  • When the number of concurrent sessions exceeds, the oldest idle session will be removed.

  • The default is 1, and this is the recommended value for better security so the system doesn't allow multiple sessions to coexist.

  • The value should match what is allowed for the application.

Testing and Validation

  • Thoroughly test the integration, especially the authentication and notification mechanisms, to ensure data mapping is accurate and able to notify the right user.

  • Validate the content of the email, including the app logo, app name, support email, copyright information, and email sender, are all correct.

  • Ensure the availability of the SSO server and webhook to provide a reliable service for the SDK backend.

Last updated