Giter VIP home page Giter VIP logo

brokeneck's Introduction

codename brokeneck

ci lerna Conventional Commits

This monorepo contains packages and applications which provide a way to manage users and groups in:

  • Auth0
  • AWS Cognito
  • Azure AD

Brokeneck Dark Brokeneck Light

Getting started

You'll need yarn and lerna installed globally:

  • npm i -g yarn lerna

The easiest way to try this out is to run the standalone server via brokeneck-fastify:

  • lerna bootstrap
  • lerna run build
  • lerna run create:env
  • configure packages/brokeneck-fastify/.env based on the authentication provider you want to use
  • packages/brokeneck-html/.env will be preconfigured with the correct REACT_APP_API_PATH for local development.
  • yarn start
  • browse to http://localhost:5001

Development

To easily develop the packages of this repo you can execute:

yarn dev

This will run:

  • brokeneck-react build in watch mode so you can change the React components and see the result immediately
  • brokeneck-html in standalone mode to have a Web UI to access
  • brokeneck-fastify in standalone mode to have a server running

Providers

Each provider requires its own configuration, as specified in brokeneck-fastify's .env.sample file.

Such configuration can be obtained when configuring the respective service using the provider's usual tooling.

There are additional requirements based on the provider, described in the next sections.

Auth0

The configured client should be authorized to access the built-in Auth0 Management API.

AWS Cognito

When using AWS cognito you must make sure that you have IAM credentials configured for the SDK in the machine running the application, for instance in the .aws/credentials file.

The configured IAM user must have access to Cognito. The simplest way to do this is to add the AmazonCognitoPowerUser AWS managed policy to the user.

Azure AD

The registered application must have all the necessary Application permissions (not Delegated permissions) to operate on the relevant objects.

These basically include all the combinations of the permissions:

  • API: Azure Active Directory Graph and Microsoft Graph
  • Objects: Directory, Users, Groups and GroupMember
  • Permissions: Read.All, ReadWrite.All, Create,

Not all combinations exists, but you should enabled them when they do.

Packages

brokeneck-react

A library of React components which provide the UI.

brokeneck-html

This package comes in 2 flavors:

  • a standalone CRA application running the UI
  • static assets containig the whole UI, which can be rendered by an external application

brokeneck-fastify

This package comes in two flavors:

  • a standalone Fastify application
  • a Fastify plugin which can be used by an external application

brokeneck-desktop

An Electron application which runs brokeneck-fastify with the embedded UI.

Usage

The packages work in synergy to support different deployment and usage scenarios, described next from the simplest to the most complex and flexible.

The important thing to keep in mind is that this application requires both a frontend and a backend.

Fully standalone

If you want to run the application standalone you can use:

  • brokeneck-fastify in standalone mode and make it render the UI by configuring the application via environment variables
  • brokeneck-desktop to run the application in desktop mode

Separate Web frontend and backend

You can run brokeneck-fastify in standalone mode without rendering the UI and brokeneck-html in standalone mode to provide the UI.

They will be two independent applications.

As a React component

You can install brokeneck-react in your React application and use the exported component.

For example, you can provide it as an additional route inside your application.

brokeneck-react has a number of peer dependencies that you have to add to your application:

npm install @material-ui/core @material-ui/lab react react-dom react-router-dom

Please check the exact versions of these packages that are required when installing brokeneck-react.

You will still need to provide a backend, which you can do either by:

  • running brokeneck-fastify in standalone mode
  • using brokeneck-fastify as a plugin inside an existing Fastify application

brokeneck's People

Contributors

bredikhin avatar davideroffo avatar dependabot[bot] avatar ekynoxe avatar guilhermelimak avatar ilteoood avatar ja-bravo avatar marco-ippolito avatar melkornemesis avatar peterabsolon avatar ramonmulia avatar renovate[bot] avatar sameer-coder avatar simoneb avatar wilkmaia avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

brokeneck's Issues

Dependency Dashboard

This issue provides visibility into Renovate updates and their statuses. Learn more

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

  • chore(deps): update dependency @rollup/plugin-commonjs to v21
  • chore(deps): update dependency eslint to v8
  • fix(deps): update dependency pkg-dir to v6

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.


  • Check this box to trigger a request for Renovate to run again on this repository

Write better documentation

the two packages which can be published require documentation: brokeneck-fastify and brokeneck-react.

expected outcome

individual packages' READMEs contains documentation

add ability to customize provider operations

right now the provider operations backing the resolvers are hardcoded and can't be changed. in the same way as we would like to let users customize the type definitions in #54 , it would make sense to consider allowing customization of provider specific operations as well.

titus integration

once the packages are published in #1, we can then create a PR in titus and integrate them.

2 options:

  • we use the fastify plugin alone which serves the UI
  • we use the fastify plugin without the UI and we render the react component inside titus

some work in this direction has already been done before this monorepo was extracted from the titus monorepo in nearform/titus#629

Auth0 pagination issue - can go to next page when no more results

This applies to both users and groups, there must be something wrong with the server side logic.

Behavior

When there are, say, 4 records in total, and page size is 2, you can go to page 2 (showing records 3 and 4) but you can also go to the next page 3, which won't show any records.

Expectation

It should not be possible to go to page 3 when there are in total 4 records and page size is 2

[umbrella issue] Search

There are multiple places in the app where searches can occur:

  • when listing users
    • cognito
    • auth0
    • azure - buggy, see #28
  • when listing groups
    • cognito - seems unsupported, to be handled in #19
    • auth0
    • azure - buggy, see #28
  • when, in the group page, adding users to the group
    • cognito
    • auth0
    • azure - buggy, see #28 (seems to work because client side autocomplete only shows matching results, but server is returning everything)
  • when, in the user page, adding the user to a group
    • cognito
    • auth0
    • azure

We should support all providers in the backend (Auth0, Azure, Cognito)

Edit user and group attributes

Currently users and groups can only be created, deleted and associated (add user to group, ...).

We need to be able to edit user and group attributes.

  • Not all attributes are editable
  • We should use GraphQL types to define what attributes are (e.g. introduce a new set of types of the likes of EditUserInput). All the attributes specified therein will be editable, perhaps with the exception of the ID which is used to identify which entity we're editing
  • We should consider using a form library for this

add ability to replace typeDefs

currently each provider's type definitions are hardcoded and they can be extended, but they cannot be replaced.

we should come up with a way to allow replacing them altogether. one option could be to:

  • expose a plugin option
  • defaulting to true
  • called something like registerDefaultProviderTypes

Pagination

There are several places in the application where pagination should happen:

  • when listing users
    • cognito
    • auth0
    • azure - buggy, see #29
  • when listing groups
    • cognito
    • auth0
    • azure - buggy, see #29
  • when listing group's users (#24)
    • cognito
    • auth0
    • azure, see #29

The backend systems implement pagination in different ways, we should support classic pagination in the client.

We should support all providers in the backend (Auth0, Azure, Cognito)

updating groups in azure does not work

the reason is that the SDK we're using does not support this operation.

we could do as we did with other operations and implement a custom operation definition, but I believe that at this stage we should just go ahead and switch to the new SDK as started in the PR associated to #22.

so, fixing this issue implies moving all operations to the new SDK first.

packaging and publishing

currently the packages work because they're part of the monorepo. we should be able to release as packages:

  • brokeneck-fastify
  • brokeneck-react

Because the fastify plugin uses the build output of the brokeneck-html package, we should consider whether we want to release that too though.

packaging brokeneck-react may require some consideration because the output is currently generated with plain babel, meaning that no dependencies are bundled. on the other hand, some dependencies should definitely not be bundles because they are those kind of dependencies which cannot run in multiple instances within the same application, as is the case for react, material ui and react-router. such dependencies should be expressed as peer dependencies instead. other dependencies (if any) could be bundled instead, but they require a more advanced mechanism, like rollup.

packaging brokeneck-fastify is simpler but also requires figuring out the dependencies and operational concerns. for instance, brokeneck-fastify registers mercurius, what if the host application also registers another instance of mercurius? I'm not even sure there is a solution to this.

expected outcome

it should be possible to npm install brokeneck-fastify and brokeneck-react and use them within a fastify and react application, respectively

Fix search component

When clearing the search input, either with the keyboard to remove the characters, or using the X button, the search results aren't updated to be the full list.

graphql-tools is deprecated

After following the get started steps, trying to run yarn start on brokeneck-fastify is erroring

Steps to reproduce

  1. Install according to the documentation.

  2. cd packages/brokeneck-fastify/, then yarn start

  3. Error displayed
    Screen Shot 2021-12-01 at 4 00 02 PM

Configuration

{
  "name": "@nearform/brokeneck-fastify",
  "version": "1.0.0-spinal.8",
  "author": {
    "name": "Simone Busoli",
    "email": "[email protected]"
  },
  "repository": "nearform/brokeneck",
  "main": "lib/plugin.js",
  "scripts": {
    "create:env": "node -r fs -e \"fs.copyFileSync('.env.sample', '.env', fs.constants.COPYFILE_EXCL)\"",
    "dev": "yarn start",
    "start": "fastify start index.js -p 5001 -l debug -w",
    "test": "tap",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "precommit": "lint-staged"
  },
  "dependencies": {
    "@azure/graph": "^5.0.1",
    "@azure/ms-rest-nodeauth": "^3.0.6",
    "@nearform/brokeneck-html": "^1.0.0-spinal.8",
    "auth0": "^2.30.0",
    "aws-sdk": "^2.793.0",
    "ejs": "^3.1.5",
    "env-schema": "^2.0.1",
    "fastify": "^3.8.0",
    "fastify-cli": "^2.5.1",
    "fastify-cors": "^6.0.0",
    "fastify-plugin": "^3.0.0",
    "fastify-static": "^4.0.0",
    "fluent-json-schema": "^3.0.0",
    "graphql": "^16.0.1",
    "graphql-iso-date": "^3.6.1",
    "graphql-tag": "^2.11.0",
    "graphql-tools": "^8.0.0",
    "mercurius": "^8.0.0",
    "pkg-dir": "^5.0.0",
    "point-of-view": "^4.7.0"
  },
  "devDependencies": {
    "babel-eslint": "^10.1.0",
    "eslint": "^7.13.0",
    "eslint-config-prettier": "^8.0.0",
    "eslint-config-standard": "^16.0.1",
    "eslint-plugin-import": "^2.22.1",
    "eslint-plugin-node": "^11.1.0",
    "eslint-plugin-prettier": "^4.0.0",
    "faker": "^5.1.0",
    "lint-staged": "^12.1.1",
    "prettier": "^2.1.2",
    "proxyquire": "^2.1.3",
    "sinon": "^12.0.1",
    "tap": "^15.0.0"
  },
  "lint-staged": {
    "**/*.js": [
      "eslint --fix"
    ]
  }
}

Handle non parity of features between providers (Group Search)

There are at least 2 things we have identified where providers work in different ways and there is no way to provide a uniform interface for them:

  • ability to search groups (cognito doesn't support it)
  • ability nest groups (cognito doesn't support it, not sure about others)

We need to describe availability of features to clients, so that the UI can reflect that.

Solution

  • expose provider metadata in the GraphQL API. There is one similar thing already, the provider name
  • enhance the Query type with a capabilities resolver, which will return a new Capabilties graphql type that clients can query to determine what features are unavailable in certain providers
  • the Capabilities type should contain one field for each capability that is different across providers
  • the Capabilities type should contain groupSearch Boolean field, which each provide populates depending on whether the feature is supported or not
  • UI will use that value to determine whether to allow users to search groups or not

automated testing

there are little to no tests. write tests.

the most important package to test is the fastify-plugin. consider writing integration tests too, hitting a real backend system like cognito, for which we have an account that can be used for automation

Azure pagination issue - can go to next page when no more results

This applies to both users and groups, there must be something wrong with the server side logic.

Behavior

When there are, say, 4 records in total, and page size is 2, you can go to page 2 (showing records 3 and 4) but you can also go to the next page 3, which won't show any records.

Expectation

It should not be possible to go to page 3 when there are in total 4 records and page size is 2

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.

Refactor react components to remove duplications

Currently there's a bit of duplicated code in various components:

  • Users and Groups
  • User and Group
  • ...

Consider extracting common code where duplication is particularly abundant.
Also consider that brokeneck is still hugely WIP, so we don't need a super optimized component layout at this stage, let's only extract the obvious smells to avoid putting us in a situation that changing code takes more effort than it should, or IOW, let's not over refactor yet.

Switch to HTTP API or different SDK for Azure

The current Azure SDK doesn't support all operations we need to do, specifically it doesn't support certain parameters we use for pagination. It forces us to use lower-level operations which are not future-proof.

We should consider switching to a more robust approach for interacting with Azure APIs, either straight HTTP or a better SDK. There is a chance that there is a more recent SDK to use, otherwise HTTP is fine too.

We are doing some HTTP interactions with Azure in Titus, if that's of any help: https://github.com/nearform/titus/blob/master/packages/titus-backend/lib/plugins/auth/azure-ad/index.js

Write tests for React components

let's use standard setup:

  • jest, unless there's a good reason not to use jest. one such reason might be that we use tap for the fastify plugin, but I'm not sure how easy writing react tests with tap is
  • RTL and RTL hooks

UI improvements

Reach out to a designer for some input about how to make the UI better.

typings

create typings for brokeneck-fastify and test them. inspire from other fastify plugins like fastify-cookie

Clear "add user to group" input field crashes application

Reproduction steps:

  • Go to an individual group page
  • Open the "Add Users" dialogue
  • Select a user in the drop down
  • Clear the input either by deleting the text with the keyboard OR clicking on the cross icon
  • Error TypeError: Cannot read property 'Username' of null appears

This does not happen with the "add to group" functionality from a single user page.
Perhaps because the input on this screen is not a searchable field.

Screenshot 2021-01-07 at 10 14 36
Screenshot 2021-01-07 at 10 14 11

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.