Security controller documentation

.travis.yml

@@ -81,7 +81,6 @@ jobs:
       script:
         - HYDRA_MAX_CONCURRENCY=20 npm run --prefix doc/framework dead-links
 
-
     - stage: Deploy Stable release on NPM
       if: branch = master AND tag IS present AND type != cron
       sudo: false

doc/6/controllers/security/create-credentials/index.md

@@ -0,0 +1,56 @@
+---
+code: true
+type: page
+title: createCredentials
+description: Creates authentication credentials for a user
+---
+
+# createCredentials
+
+Creates authentication credentials for a user.
+
+<br />
+
+```js
+createCredentials(strategy, kuid, credentials, [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `strategy` | <pre>string</pre> | Strategy to use |
+| `kuid` | <pre>string</pre> | User [kuid](/core/1/guides/essentials/user-authentication/#kuzzle-user-identifier-kuid) |
+| `credentials` | <pre>object</pre> | New credentials |
+| `options` | <pre>object</pre> | Query options |
+
+### credentials
+
+The credentials to send. The expected properties depend on the target authentication strategy.
+
+Example for the `local` strategy:
+
+```js
+{
+  username: 'foo',
+  password: 'bar'
+}
+```
+
+### options
+
+Additional query options
+
+| Property | Type<br />(default) | Description |
+| --- | --- | --- |
+| `queuable` | <pre>boolean</pre><br />(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+| `refresh` | <pre>boolean</pre><br />(`false`) | If set to `wait_for`, Kuzzle will not respond until the credentials are indexed |
+
+## Resolves
+
+An `object` representing the new credentials.  
+The content depends on the authentication strategy.
+
+## Usage
+
+<<< ./snippets/create-credentials.js

doc/6/controllers/security/create-credentials/snippets/create-credentials.js

@@ -0,0 +1,23 @@
+try {
+  await kuzzle.security.createUser('foo', {
+    content: {
+      profileIds: ['default'],
+      fullName: 'John Doe'
+    },
+    credentials: {}
+  });
+
+  const response = await kuzzle.security.createCredentials(
+    'local',
+    'foo',
+    { username: 'foo', password: 'bar' }
+  );
+  console.log(response);
+  /*
+    { username: 'foo' }
+  */
+
+  console.log('Credentials successfully created');
+} catch (e) {
+  console.error(e);
+}

doc/6/controllers/security/create-credentials/snippets/create-credentials.test.yml

@@ -0,0 +1,6 @@
+name: security#createCredentials
+description: Creates credentials for the specified strategy
+hooks:
+  after: curl -X DELETE kuzzle:7512/users/foo?refresh=wait_for
+template: default
+expected: Credentials successfully created

doc/6/controllers/security/create-first-admin/index.md

@@ -0,0 +1,66 @@
+---
+code: true
+type: page
+title: createFirstAdmin
+description: Creates a Kuzzle administrator account, only if none exist.
+---
+
+# createFirstAdmin
+
+Creates a Kuzzle administrator account, only if none exist.
+
+<br />
+
+```js
+createFirstAdmin(kuid, body, [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `kuid` | <pre>string</pre> | Administrator [kuid](/core/1/guides/essentials/user-authentication/#kuzzle-user-identifier-kuid) |
+| `body` | <pre>object</pre> | Administrator content &amp; credentials |
+| `options` | <pre>object</pre> | Query options |
+
+### body
+
+The `body` property must contain two objects:
+- `content`: Administrator additional information. Can be left empty.
+Any other attribute can be added. 
+Make sure to [update the user mapping](/sdk/js/6/controllers/security/update-user-mapping) collection to match your custom attributes.
+- `credentials`: Describe how the new administrator can be authenticated. This object must contain one or more 
+properties, named after the target authentication strategy to use. Each one of these properties are objects
+containing the credentials information, corresponding to that authentication strategy.
+
+Example: 
+
+```js
+{
+  content: {
+    firstName: 'John',
+    lastName: 'Doe'
+  },
+  credentials: {
+    local: {
+      username: 'admin',
+      password: 'myPassword'
+    }
+  }
+}
+```
+
+### options
+
+| Property | Type<br />(default) | Description |
+| --- | --- | --- |
+| `queuable` | <pre>boolean</pre><br />(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+| `reset` | <pre>boolean</pre><br />(`false`) | If true, restricted permissions are applied to `anonymous` and `default` roles |
+
+## Resolves
+
+An [`User`](sdk/js/6/core-classes/user/introduction) object containing information about the newly created administrator.
+
+## Usage
+
+<<< ./snippets/create-first-admin.js

doc/6/controllers/security/create-first-admin/snippets/create-first-admin.js

@@ -0,0 +1,37 @@
+try {
+  const response = await kuzzle.security.createFirstAdmin(
+    'admin',
+    {
+      content: {
+        firstName: 'John',
+        lastName: 'Doe'
+      },
+      credentials: {
+        local: {
+          username: 'admin',
+          password: 'myPassword'
+        }
+      }
+    }
+  );
+
+  console.log(response);
+  /*
+  User {
+    _id: 'admin',
+    content:
+      { profileIds: [ 'admin' ],
+        firstName: 'John',
+        lastName: 'Doe',
+        _kuzzle_info:
+          { author: '-1',
+            createdAt: 1560351009496,
+            updatedAt: null,
+            updater: null  } } }
+   */
+
+  console.log('First admin successfully created');
+
+} catch (e) {
+  console.error(e);
+}

doc/6/controllers/security/create-first-admin/snippets/create-first-admin.test.yml

@@ -0,0 +1,6 @@
+name: security#createFirstAdmin
+description: Creates first admin
+hooks:
+  after: curl -X DELETE kuzzle:7512/users/admin?refresh=wait_for
+template: default
+expected: First admin successfully created

doc/6/controllers/security/create-or-replace-profile/index.md

@@ -0,0 +1,45 @@
+---
+code: true
+type: page
+title: createOrReplaceProfile
+description: Creates a new profile or, if the provided profile identifier already exists, replaces it.
+---
+
+# createOrReplaceProfile
+
+Creates a new profile or, if the provided profile identifier already exists, replaces it.
+
+<br />
+
+```js
+createOrReplaceProfile(id, body, [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | <pre>string</pre> | Profile identifier |
+| `body` | <pre>object</pre> | Profile definition content |
+| `options` | <pre>object</pre> | Query options |
+
+### body
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `policies` | <pre>object</pre> | [Profile content](/core/1/guides/essentials/security/#defining-profiles) |
+
+### options
+
+| Property | Type<br />(default) | Description |
+| --- | --- | --- |
+| `queuable` | <pre>boolean</pre><br />(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+| `refresh` | <pre>boolean</pre><br />(`false`) | If set to `wait_for`, Kuzzle will not respond until the created/replaced profile is indexed |
+
+## Resolves
+
+A [`Profile`](/sdk/js/6/core-classes/profile/introduction) object representing the updated/created profile.
+
+## Usage
+
+<<< ./snippets/create-or-replace-profile.js

doc/6/controllers/security/create-or-replace-profile/snippets/create-or-replace-profile.js

@@ -0,0 +1,37 @@
+try {
+  const response = await kuzzle.security.createOrReplaceProfile(
+    'myProfile',
+    {
+      policies: [
+        {
+          roleId: 'default'
+        },
+        {
+          roleId: 'admin',
+          restrictedTo: [
+            {
+              index: 'someIndex',
+              collections: [
+                'collection1',
+                'collection2'
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  );
+  console.log(response);
+
+  /*
+  Profile {
+    _id: 'myProfile',
+    policies:
+      [ { roleId: 'default' },
+        { roleId: 'admin', restrictedTo: [Array] } ] }
+  */
+
+  console.log('Profile successfully updated');
+} catch (e) {
+  console.error(e);
+}

doc/6/controllers/security/create-or-replace-profile/snippets/create-or-replace-profile.test.yml

@@ -0,0 +1,6 @@
+name: security#createOrReplaceProfile
+description: Create or replace a profile
+hooks:
+  after: curl -XDELETE kuzzle:7512/profiles/myProfile?refresh=wait_for
+template: default
+expected: Profile successfully updated

doc/6/controllers/security/create-or-replace-role/index.md

@@ -0,0 +1,45 @@
+---
+code: true
+type: page
+title: createOrReplaceRole
+description: Creates a new role or, if the provided role identifier already exists, replaces it.
+---
+
+# createOrReplaceRole
+
+Creates a new role or, if the provided role identifier already exists, replaces it.
+
+<br />
+
+```js
+createOrReplaceRole(id, body, [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | <pre>string</pre> | Role identifier |
+| `body` | <pre>object</pre> | Role definition content |
+| `options` | <pre>object</pre> | Query options |
+
+### body
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `controllers` | <pre>object</pre> | [Role definition](/core/1/guides/essentials/security/#defining-roles) |
+
+### options
+
+| Property | Type<br />(default) | Description |
+| --- | --- | --- |
+| `queuable` | <pre>boolean</pre><br />(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+| `refresh` | <pre>boolean</pre><br />(`false`) | If set to `wait_for`, Kuzzle will not respond until the created/replaced role is indexed |
+
+## Resolves
+
+A [`Role`](/sdk/js/6/core-classes/role) object representing the created/replaced role.
+
+## Usage
+
+<<< ./snippets/create-or-replace-role.js

doc/6/controllers/security/create-or-replace-role/snippets/create-or-replace-role.js

@@ -0,0 +1,52 @@
+try {
+  const response = await kuzzle.security.createOrReplaceRole(
+    'read-only',
+    {
+      controllers: {
+        auth: {
+          actions: {
+            getCurrentUser: true,
+            getMyCredentials: true,
+            getMyRights: true,
+            logout: true
+          }
+        },
+        collection: {
+          actions: {
+            getMapping: true,
+            list: true
+          }
+        },
+        document: {
+          actions: {
+            count: true,
+            get: true,
+            mGet: true,
+            scroll: true,
+            search: true
+          }
+        },
+        index: {
+          actions: {
+            list: true
+          }
+        }
+      }
+    }
+  );
+  console.log(response);
+  /*
+  Role {
+    _id: 'read-only',
+    controllers:
+      { auth: { actions: [Object] },
+        collection: { actions: [Object] },
+        document: { actions: [Object] },
+        index: { actions: [Object] }  } }
+   */
+
+  console.log('Role successfully updated');
+
+} catch (e) {
+  console.error(e);
+}