--- title: Authentication slug: v4-4/authentication docTags: createdAt: 2023-08-23T02:54:07.671Z --- 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`. :::hint{type="info"} For example implementations, see the getditto > [sample-authentication-permissions](https://github.com/getditto/sample-authentication-permissions) repository in GitHub. ::: # Get started These sections will describe how you can: 1. Identify users 2. Give users read or write control 3. 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](docId\:MNF4j6B1_-W8XhETMm0Ha) which you specify. This information is used to accept or reject syncronization with peers. ## Playground Identity 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](docId\:c802C1qiAkfgA2QxmcyWu) - for prototyping with Ditto for hybrid offline/online synchronization. Start here! :::hint{type="warning"} 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](docId\:gXAdbUACkIJGYg9wkARM3). ::: 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. ## Production Identities Once you are ready to deploy, this can be swapped for a production identity where security is enforced. - [OnlineWithAuthentication](docId\:hEdG-fcYV5i54wBxXHFut) - for hybrid offline/online applications. - [Shared Key](docId\:hKUSvoOWAWc9N46lyXUWE) for offline-only enterprise applications where all devices are trusted. ## Parts of a Ditto Identity For more detailed information on what is contained within Ditto Identity certificates, see [Certificate-Based Security](docId\:fP1VrRUeHQ9XOAVv0VlG3). # Ditto Identity Lifecycle 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[​](https://deploy-preview-643--shiny-croquembouche-15669a.netlify.app/ios/common/security/authentication#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). :::hint{type="warning"} 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. ![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/rul-oU4qh4gojuEICoAxn_auth-flow.png)