@libresat/identity

Simple and secure role-based authentication, authorization & identity provider implemented as a GraphQL microservice for [LibreSat](https://libresat.space/)

Stats

StarsIssuesVersionUpdatedCreatedSize
@libresat/identity
0.0.1-203 years ago3 years agoMinified + gzip package size for @libresat/identity in KB

Readme

LibreSat Identity

Simple and secure role-based authentication, authorization & identity provider implemented as a GraphQL microservice for LibreSat.

Demo Site Code License AGPL-3.0 Media License CC-BY-SA-4.0 Part of LibreSat Infrastructure Overview

Usage

# Install dependencies
npm install
# Build and serve development version on http://localhost:3000
npm run dev
# Build and serve production version on http://localhost:3000
npm run build
npm start

Documentation

Models

Name Description Example
scope Group of items that a user can have access to privateSection
role Type of access that a user can have in a scope READ:USERS
user Entity with roles and scopes yourUsername

Typical usage

Create Scope

First, create a scope with the name scope1:

Request:

mutation {
  createScope(name: "scope1") {
    _id
  }
}

Response:

{
  "data": {
    "createScope": {
      "_id": "5ba566e48d13c2239e6ba95b"
    }
  }
}

Note down the ID.

Create Role

Secondly, create a role with the name WRITE:EVERYTHING:

Request:

mutation {
  createRole(name: "WRITE:EVERYTHING") {
    _id
  }
}

Response:

{
  "data": {
    "createRole": {
      "_id": "5ba568108d13c2239e6ba95e"
    }
  }
}

Note down the ID.

Create User

Now, create a user with the name user1 and password password1:

Request:

mutation {
  createUser(name: "user1", password: "password1") {
    _id
    password
  }
}

Response:

{
  "data": {
    "createUser": {
      "_id": "5ba5685a8d13c2239e6ba95f",
      "password": "$2a$10$Ntq.OQ2krtNkZal/xbsl1OHZb2mjkZ2T5pjhLc5wVopcOLWvVA.y6"
    }
  }
}

Assign role to scope

To start linking the models together, assign the role to the scope:

Request:

mutation {
  assignRoleToScope(
    scopeId: "5ba566e48d13c2239e6ba95b"
    roleId: "5ba568108d13c2239e6ba95e"
  ) {
    name
  }
}

Response:

{
  "data": {
    "assignRoleToScope": {
      "name": "scope1"
    }
  }
}

Now we've got a role that is linked to a scope.

Assign user to scope

In oder to give the user access to the scope, we need to assign them to the scope as well.

Request:

mutation {
  assignUserToScope(
    scopeId: "5ba566e48d13c2239e6ba95b"
    userId: "5ba5685a8d13c2239e6ba95f"
  ) {
    name
  }
}

Response:

{
  "data": {
    "assignUserToScope": {
      "name": "scope1"
    }
  }
}

Assign role to user

Now, let's assign the the WRITE:EVERYTHING role, which the organization now has, to the user. As you might remember, the role specifies which type of access the user should have to the scope (i.e., like in this example, the capability to write to all objects within it):

Request:

mutation {
  assignRoleToUser(
    roleId: "5ba568108d13c2239e6ba95e"
    userId: "5ba5685a8d13c2239e6ba95f"
  ) {
    name
  }
}

Response:

{
  "data": {
    "assignRoleToUser": {
      "name": "user1"
    }
  }
}

Auth a user with a role inside a scope

Hooray! user1 should now be able to access scope1 with the WRITE:EVERYTHING role. Let's test it!

First, set the HTTP headers for authentication:

Key Value
userid 5ba5685a8d13c2239e6ba95f
password password1

Next, send a authorization mutation:

Request:

mutation {
  auth(
    scopeId: "5ba566e48d13c2239e6ba95b"
    validRolesNames: ["WRITE:EVERYTHING"]
  ) {
    _id
    name
  }
}

Response:

{
  "data": {
    "auth": {
      "_id": "5ba5685a8d13c2239e6ba95f",
      "name": "user1"
    }
  }
}

It works! We were able to authenticate and authorize a user within a scope using his role. If we specify a role which the user does not support (or the organization does not have), or use the wrong credentials for authentication, we will get an error message:

Request:

mutation {
  auth(
    scopeId: "5ba566e48d13c2239e6ba95b"
    validRolesNames: ["WRITE:EVERYTHING", "WRITE:ADMIN"]
  ) {
    _id
    name
  }
}

Response:

{
  "data": null,
  "errors": [
    {
      "message": "Authorization failed, user does not have the necessary priviledges!",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["auth"]
    }
  ]
}

Of course, you can do much more using LibreSat Identity. Simply fire up your own instance as described in Usage and check out the GraphQL documentation by visiting it's URL!

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.