github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/archives/onboarding.md (about) 1 [Table of contents](../README.md#table-of-contents) 2 3 This document was written in november and december 2016. 4 5 # Onboarding 6 7 This document explains the architecture and process allowing a cozy instance 8 owner to register to its cozy instance. 9 10 Compatibility with the current developments on cozy onboarding is a goal : 11 [The following documents has been consulted for this proposal](https://github.com/cozy/cozy-proxy/blob/bf9af7f2342e3fc183a8b4e72bcedb909afa3eb8/docs/client/) 12 13 ## Instance creation 14 15 Creating an instance is done through CLI or through the (future) partner farm 16 manager system. Some **settings** can be pre-defined on instance creation. 17 ([doc](../instance.md#creation)). 18 19 The CLI also allows to specify which source to use for `onboarding` and `home` 20 applications. The defaults will be hosted on `github.com/cozy`. 21 22 After creation, an instance has a `registerToken` generated randomly. 23 24 ## Onboarding steps 25 26 This document and the cozy-stack are only concerned with login and passphrase 27 registering step which are important for security. 28 29 All other steps are handled by the `onboarding` application. 30 31 The `onboarding` application SHOULD therefore provide the following features 32 33 - When started with a `registerToken`, allow the user to create a passphrase 34 - When started with a `contextToken` 35 ([see auth doc](../auth.md#how-to-get-a-token)) use it to retrieve instance 36 document. 37 - If the instance document is complete **according to the `onboarding` 38 app**, redirect to `home` application. 39 - Otherwise, performs whatever steps it deems necessary to fill out the 40 instance (ask for user email, help set up `myaccounts` accounts, say 41 thank you...) 42 43 This makes cozy-stack simple and safer while allowing behaviour modification for 44 several install types by picking the correct `onboarding` application / branch. 45 46 This makes it easier to add more onboarding steps and have them run on 47 already-installed cozy: On next login after onboarding application update, it 48 will ask the user. 49 50 ## Redirections 51 52 When an user attempts to access the root of its instance 53 (`https://example.cozycloud.cc`) or an application 54 (`https://contacts.example.cozycloud.cc`), and she is not logged-in, she is 55 redirected : 56 57 - If the instance has a `passphrase` set, to the `/login` page 58 - If the instance has a `registerToken` set, to the `onboarding` application. 59 60 After login, the user is always redirected to the `onboarding` application. It 61 is the `onboarding` application responsibility to check if registering is 62 complete and reredirect to home. 63 64 ## Routes 65 66 See [settings](../settings.md). 67 68 ## Flow Example 69 70 - The server administrator Bob creates an instance through the CLI. He knows 71 the instance should be in french for an user named `alice`. 72 73 ``` 74 cozy-stack instances add alice.example.com --locale fr 75 >> https://alice.cozycloud.cc?registerToken=42456565213125454842 76 ``` 77 78 The instance is created 79 80 ```json 81 { 82 "domain": "alice.example.com", 83 "locale": "fr" 84 } 85 ``` 86 87 - Eve knows Alice just had an instance created, she goes to 88 `https://alice.cozycloud.cc`. There is no `registerToken`, so she only see a 89 message (in french) along the lines of "This is the cozy for Alice Martin, 90 this register link is incorrect, if you are Alice Martin please ask your 91 sysadmin for a new link". 92 - Alice navigates to `https://alice.cozycloud.cc?registerToken=42...42` 93 - She is redirected to the `onboarding` application 94 - The `onboarding` application receive the registerToken. It is the default 95 onboarding application and therefore display the cozy cloud agreement and 96 then ask for a Password. 97 - The `onboarding` application use its `registerToken` to register the 98 passphrase. Registering the passphrase automatically log Alice in and 99 redirect her back to the `onboarding` app. 100 - Afterward, the `onboarding` app receive its token normally through the 101 `data-cozy-token` body attribute, as described in 102 [auth documentation](../auth.md). and can do whatever it needs to do : 103 - read from the instance document to prefill/bypass form fields 104 - add more informations to the instance document. 105 - create `io.cozy.accounts` documents for external accounts. 106 - When the onboarding application is satisfied, Alice is redirected to the 107 `home` application