Authentication
Ditto does not come with an identity provider. Using OnlineWithAuthentication requires that you have your own identity provider already set up. Each app can use multiple identity providers.
The OnlineWithAuthentication identity type is geared towards apps that will be deployed in real world settings. OnlineWithAuthentication identity types are:
- for apps that need to integrate with existing permissions
- for apps that need to integrate with existing authentication systems
To do this, you must use either OnlinePlayground or OnlineWithAuthentication.
For example implementations, see the getditto > sample-authentication-permissions repository in GitHub.
These sections will describe how you can:
- Identify users
- Give users read or write control
- Integrate with your existing authentication systems
There are several types of identities. Every installation of an app that uses Ditto has its own identity. This identity is used to identify each unique peer in the mesh network.
Each Ditto Identity is associated to a single Ditto client via a globally unique identifier and may not be used across multiple Ditto apps. Each identity has an appID, an authentication certificate, and a set of Access Control Permissions which you specify. This information is used to accept or reject syncronization with peers.
When you start prototyping with Ditto you can use a playground identity. The playground identitiy offers no real security.
Once the device connects to the internet, the Big Peer generates a X.509 certificate that ensures Small Peer devices connected in the mesh can sync with each other while online and offline. Once offline, the Small Peer remains authenticated for one week. After one week, the certificate expires and the Small Peer must reconnect to the internet to retrieve a new certificate.
The Big Peer’s replication engine includes an HTTPS authentication service that handles login requests. Before Small Peer devices can sync with other peers in the mesh network, they must connect to the internet at least once in order to authenticate and retrieve their signed client certificate and access credentials from the Big Peer cloud server. Once connected to the Big Peer at least once, use the OnlinePlayground API to authenticate.
Authentication and Initialization - for prototyping with Ditto for hybrid offline/online synchronization. Start here!
Unless you have a federal use case, you must connect to the internet at least once to retrieve an authentication certificate from the Big Peer cloud deployment before you can sync offline with other peers.
If you have a federal use case, such as a government app, contact Ditto for next steps. For contact information, see Support.
The Big Peer’s replication engine includes an HTTPS authentication service that handles login requests. Before Small Peer devices can sync with other peers in the mesh network, they must connect to the internet at least once in order to authenticate and retrieve their signed client certificate and access credentials from the Big Peer cloud server. Once connected to the Big Peer at least once, use the OnlinePlayground API to authenticate.
Once you are ready to deploy, this can be swapped for a production identity where security is enforced.
For more detailed information on what is contained within Ditto Identity certificates, see Certificate-Based Security.
While highly configurable, each Ditto Identity has a typical life cycle. First, the Ditto Identity is constructed. Typically the only prerequisites are a Ditto persistence root (working directory for local data storage, where configured) and a globally unique Ditto AppId. In order to sync, all app instances, regardless of SDK language, must have the same globally unique Ditto AppId. Therefore this value will typically be incorporated in the App's bundle or provided to the App when it starts. The Ditto Big Peer can create AppIds for you, but it is not the authentication provider. Ditto Cloud is a proxy to your own "source of truth" for identities, credential validation, and permissions.
Next the Ditto Identity is consumed by the Ditto constructor, yielding a configured Ditto instance. The Ditto instance will contain a Ditto Authenticator and your own implementation of the DittoAuthEventHandler interface, which can provide login credentials. Ditto will then contact the configured Auth Url and supply the login credentials to an Authentication Provider. If the credentials are valid, then the Authentication Provider will return to Ditto an Authentication Token, validating its credentials and granting the Ditto instance individualized permissions. The Ditto instance can now sync with other peers.
How it works
To use the "Online With Authentication" system, your client application is expected to authenticate with your identity system and retrieve some sort of token prior to syncing with Ditto. Often times this token is some sort of identity token, access token, commonly in the format of a JWT (JSON Web Token).
Devices using Online with Authentication need to connect to the Internet and authenticate at least once before synchronizing with other peers. This is required so devices can get a valid certificate before going offline.
Once your client application successfully has retrieved this token, it should pass it to the Ditto authenticator which will pass it to an authentication webhook. As the developer, you are responsible for writing code and deploying the this webhook to an accessible URL. The authentication webhook will validate and decode the token from the client side and return identity and access control information back to your Ditto instance.
