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