Client Manager

Client Manager is a mountable Rails (engine) gem that helps identify and authenticate your API clients.

Motivation

To understand why this gem exists, let's look at a simple example of a blog application built with a Rails API and any JavaScript front-end framework. In the API, you're probably going to have some endpoints that only logged in Users/Authors can access. Like creating or deleting a blog post. Other endpoints, however, like reading posts, will be unauthenticated. This means that if one should go to the read endpoint using a browser, the whole JSON response will be displayed. What would be ideal, would be make it such that only the front-end application can access the read endpoint(s).

Typically to do this, you might generate a random UUID and ask the front-end developer to put it in the header of their requests. But this doesn't scale well. What if you want to add an Android app? Or an iOS one too? That's where Client Manager comes in. It helps you easily manage all of this with a simple User Interface. With Client Manager, you can:

• Create clients with an automatically generated JSON Web Token, which can be used to authenticate requests
• Create users with the ability to create (a specified number of) clients themselves

Prerequisites

• Rails 5 and above

Installation & Setup

1. Add the gem to your Gemfile

Add the following line to your application's Gemfile:

gem 'client_manager', '~> 0.1.0'

Run:

bundle install

2. Migrate the database

Run the following command in your terminal:

rake db:migrate

3. Install Client Manager

Run the following command in your terminal:

rails generate client_manager:install

This creates a client_manager.rb file in your app's initializer's folder and inserts include ClientManager::Concerns::SetClientByToken into your ApplicationController to authenticate all requests. You can remove it from that controller and put it in any controller that needs client authentication.

Note if your app is an API-only application, Client Manager will do the following:

• Remove config.api_only = true from application.rb
• Add config.middleware.use ActionDispatch::Flash to application.rb
• Uncomment # require "sprockets/railtie" in application.rb

In your client_manager.rb file, you need to set config.token_secret (to a random secure UUID). It's set to nil by default and would raise an error if you try to create clients without setting it.

4. Create a SuperAdmin Account

Finally, you need to create a superadmin account for yourself using the following command:

rake client_manager:superadmin NAME=YOUR_NAME_HERE EMAIL=YOUR_EMAIL_HERE PASSWORD=YOUR_PASSWORD_HERE

For example:

rake client_manager:superadmin NAME=Timi [email protected] PASSWORD=lol

All three arguments are required.

5. Start your server

Usage

The Client Manager is automatically hosted at /client_manager. There, you can sign in with your superadmin credentials and start using the application.

Creating Users

Once, signed in, you can create Client Manager Users and specify the maximum number of clients they are allowed to create. Users you create will get an email with their password and are required to change this on first sign in.

Note: Client Manager inherits from your application's ActionMailer settings. If you've not set up your application to send emails, client manager emails WILL NOT get sent. You can see the email content in your server logs. Read more about ActionMailer.

Creating Clients

You can create clients yourself, or let your users create clients. To create a Client, click the server icon in the navigation to go to the Clients page. Then, click the plus sign to create a new client.

Authenticating Requests

Client applications need to add their generated tokens to the Header of every request. For example -

fetch(apiUrl, {
    method: 'GET',
    headers: new Headers({ 'client_token': GENERATED_TOKEN_HERE })
});

You can access the client making the request within your controllers using the current_client helper method.

Contributing & Todo

To contribute: fork this repo, write code & make pull request. Some of the things I'm looking at doing in the immediate future are:

• Tests
• Basic stats: Requests per client over time
• Rate limiting client requests

License

The gem is available as open source under the terms of the MIT License.