Skip to content

Index

Channel SSO requirements

The primary method of authentication for the app will always be authentication tokens issued by, and valid for, the backend of The Dots. Once our backend has issued a token, we use that to authenticate with our own backend until there is a need to verify third party authentication to authorise access to containers or other features. We also verify with the third party upon app launch.

  • We do not synchronise with third party systems in either direction. Third party systems are communicated with on an ad-hoc basis as necessary
  • As such, revoking access or removing a user in an external system will not revoke our own authentication tokens (meaning users will remain logged in), delete accounts or revoke channel access.
  • To revoke access to the channel, we provide webhook endpoints that may be called by the external systems
  • SSO may be used to connect the external account to an existing Dots account or create a new one
  • Existing Dots accounts will not be altered in any way (aside from storing the third party authentication token), nor will any of their information be transmitted outside of our systems

Technical Implementation

All connections to external systems must be secured via TLS 1.2 or newer. We do not integrate external SDKs to ensure code stability and security, nor do we at any point capture user input to be sent directly to external systems.

The SSO backend must provide a unique immutable user ID for each user. It must not be an email address.

Authentication Flow

Solutions other than OAuth2 are possible, but are out of scope and require additional development time.

A fullscreen webview with a URL of your choosing will be loaded, where the user can then log into your systems. At this point the app is not in control and it is up to the SSO provider to apply the appropriate visuals (branding, responsiveness). Once authentication is complete, the user must be redirected to a URL we will provide, with an authorisation code as a query parameter. At this point the app will take control again and send the authorisation code to our backend systems, which will in turn exchange said code for a tokenset with the SSO backend.

This tokenset is then used to retrieve a user's external profile, which we use to pre-fill any sign-in/signup forms in order to speed up that process. Only the tokenset will be stored after our login/signup process is complete, any other information from the external system will not be stored. The tokenset will be used in the situations described above to (re-)authorise users when necessary; the refresh token will be used to refresh the access token as/when required.

Note

We will not automatically sign users in based on any data match between the external data and our own data for security reasons, users will always have to authenticate.

Feature Flags

Our backend will pass any feature flags returned by the SSO backend in a user's profile data to the app as necessary. The profile data structure is flexible and we will parse it as necessary, but each feature flag must be a simple boolean value that controls exactly one feature. We do not parse and process any subscription/membership structures in order to determine access. This must be done by the external system, as maintaining this logic would add significant overhead and complexity.

An example profile could be:

JSON
{
    "id": "3d6479fe-6f41-41e1-bd2b-d5139e21de58",
    "email": "jane.doe@email.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "features": {
        "canAccessApp": true,
        "canAccessContainer1": false,
        "canAccessContainer2": true
    }
}

The app and our backend would handle these as follows:

  • Upon app launch, we retrieve the user's profile and validate that canAccessApp is true; failure to retrieve a profile or the flag being set to false would log the user out
  • When accessing one container, we retrieve the user's profile and validate that canAccessContainer1 is true; if not, display an error
  • For another container we may do the same but validate against canAccessContainer2

Note that this access may also be checked by the website loaded in the webview, using the authentication token passed in the Authorization header. For the best experience we recommend doing so, as this could be used to dynamically upsell users for example. In our experience this is often already the case anyway, so it may not be necessary to explicitly control containers via feature flags.

Deliverables

These are the deliverables we require in order to implement SSO:

  • URL for the SSO authentication process
  • URL for an endpoint to retrieve user profile information
  • This may be provided by means of API documentation as well, as long as we know which URL to retrieve and how to authenticate it
  • A list of feature flags and their purpose

Design Implementation

We will be working from a detailed deck for design requirements which will be shared with you separately.

Legals

We require the following legal documents from you at designated points in the project:

  • Privacy Policy
  • Terms & Conditions
  • Joint Controller Statement

You must seek your own legal advice about these documents but we are happy to provide you with our own documents or examples from other clients if appropriate.

Documents can be provided to us in PDF format but we can also point to a web view if you already host this information. A web view has the benefit of not requiring an app update each time a policy is updated.

Optional features

Profile Data

We do allow the user to import some of the information stored in the external system upon first signup. However, the data we import is limited to a handful of fields, subject to restrictions and users may modify the information before it is stored. This is a one-time process that is not repeated during the life cycle of a member account. For users who already have an account in our system, we do not import any data. It is not possible for external systems to modify any of a user’s stored information at any point. We currently support importing the following data:

  • First Name; no longer than 100 bytes
  • Last Name; no longer than 100 bytes
  • Email Address; must be a valid email address, no longer than 150 bytes
  • Biography (or “about”); no size restriction, but plain text only. New lines are retained, but HTML content is not allowed and will be stripped. We do not support markup of any kind (e.g. Markdown)

An example profile could be:

JSON
{
    "id": "3d6479fe-6f41-41e1-bd2b-d5139e21de58",
    "email": "jane.doe@email.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "biography": "This is my biography,\n\nwith multiple lines.",
    "features": {
        "canAccessApp": true,
        "canAccessContainer1": false,
        "canAccessContainer2": true
    }
}

Containers / Webviews

At various points in the app we offer the opportunity to have webviews where we embed a webpage hosted by you - we call these Containers. They are almost identical to Safari on iOS and Chrome on Android in terms of functionality and rendering capabilities. Anything in these webviews should be responsive. Unlike the webviews used for SSO, they are not fullscreen.

Capabilities

URLs must be identical for all users, with two exceptions:

  • We can pass the authentication token from your SSO backend along in various ways
    • In an HTTP header (e.g. the Authorization header)
    • As a query parameter
  • The same goes for the user ID as returned by your SSO backend
    • This can be included in the same methods as the authentication token

This would allow your web backend to authenticate the user’s access and present them with the appropriate content. We can also switch between different URLs based on feature flags returned by your SSO backend for specific containers, if so desired. Similarly, we can show or hide specific containers based on the feature flags.

Deliverables

These are the deliverables we require in order to implement SSO:

  • A list of containers and their URLs
  • Whether they should be authenticated with an authentication token in an HTTP header or query parameter
  • Whether they should include the user ID in an HTTP header or query parameter

Passes (“check-in”)

The Dots offers 2 methods of providing guest passes to be used for a variety of purposes, including (but not limited to) on-location check-in.

We currently only offer this for iOS apps.

Generating and managing these passes and their physical use is not covered by this offering, The Dots only facilitate retrieving the passes and adding them to the Apple Wallet.

Implementation

  • We only accept .pkpass files (Apple’s native format), no other formats, nor bundles of .pkpass files (.pkpasses)
  • Passes must be provided as fully qualified direct URLs to the .pkpass files in one of two ways:
    • In the data returned from your primary SSO account retrieval endpoint
    • As a dedicated endpoint to be called with the member’s authentication token (both from your SSO, more details below)
  • All passes are treated equally in that we do not distinguish between different types of passes when there are multiple; we will however maintain the order of passes as it is in the data you provide to us and will present the first one as the “primary” pass
  • Within the app’s UI, we will present the passes to the member in an overlay, which may be triggered from the following actions:
    • A menu item in the hamburger menu. Draft design here.
    • TBD, designs are pending
  • From this overlay, members may add passes to their Apple Wallet for actual use
    • Visuals for the passes themselves will be taken from the .pkpass files

Backend Endpoints

If you provide the passes in the member’s SSO account data, the data structure is flexible as long as there are fully qualified URLs to the passes available within said data. Note that this must be the same endpoint we use to retrieve a member’s basic account details and feature flags.

If you wish to use a dedicated endpoint, it must be authenticated with the user’s authentication token as provided by your SSO and it must respond with the following structure (a flat array of URLs in JSON format):

JSON
[
  "https://your-url.com/guest-passes/primary-pass.pkpass",
  "https://your-url.com/guest-passes/other.pkpass"
]

Guidance on creating and managing passes

Apple offer the following documentation on creating, managing and distributing .pkpass files:

  • Creating the info for the pass: here

  • Generating the pass: here

  • Distributing the pass: here

There are also third party services you can use to aid in this effort (e.g. PassKit.com).

Some examples of what is possible in a pass in the Apple Wallet:

Image title Image title

Loading Animation

You can have a custom loading icon. This animated loading icon will sometimes show up briefly when app screens are loading.

For this icon, we use an animation framework developed by Airbnb called Lottie: https://github.com/airbnb/lottie-ios

Lottie loads and renders animations and vectors exported in the ‘bodymovin JSON’ format. Bodymovin JSON can be created and exported from either; After Effects with bodymovin, Sketch with Lottie Sketch Export, or Haiku.

For more info, head here: https://lottiefiles.com/what-is-lottie

Deliverables

  • Loading animation file in 'bodymovin JSON' format.