popphp/kettle-auth

1.0.0 2017-05-18 14:37 UTC

README

kettle-auth is a simple user authentication REST API. It allows for client applications to execute user authentications using tokens. It also allows for some basic user management, such as registering, updating or deleting users from the application.

The Kettle Namespace is a set of tools built using components from the Pop PHP Framework.

Installation

kettle-auth comes with the database schemas for MySQL, PostgreSQL and SQLite. Load the preferred schema into your database, and copy the file app/config/app.web.orig.php to app/config/app.web.php and load the corresponding database credentials into the new config file.

Top

Authentication

The default username and password are admin and password. For the examples below, the PHP CLI server is used at http://localhost:8000/. Please note, it is strongly recommended that you use https in production.

Authenticate

You can perform an initial authentication to the server in one of two ways. You can pass the username and password as data via POST:

curl -i -X POST -d"username=admin&password=password" http://localhost:8000/auth

Or, you can pass the username and password as a base64 encoded string, in this case base64_encode('admin:password');, in a basic Authorization header:

curl -i -X POST --header "Authorization: Basic YWRtaW46cGFzc3dvcmQ=" http://localhost:8000/auth

and, if successful, you will receive information about the user and the appropriate session tokens to store with your client application to maintain the user's session and to continue to execute authentications with the server.

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE
WWW-Authenticate: Basic

{
    "id": 1,
    "username": "admin",
    "active": 1,
    "manage": 1,
    "token": "1f98dc780e22c751d8d6203d6c5c786e192136f1",
    "refresh": "2c9b3b2114bec3d2ffd12c9155a9639c0899aa25",
    "expires": 1495056729
}

If unsuccessful, you will simply receive a 401 Unauthorized response:

HTTP/1.1 401 Unauthorized
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

Top

Validate the Token

Once you have a valid authentication token, you can continue to request valid authentication with that token like this:

curl -i -X POST --header "Authorization: Bearer 1f98dc780e22c751d8d6203d6c5c786e192136f1" \
  http://localhost:8000/token

With the valid token, you will receive a 200 OK response:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

And with an invalid token, you will receive a 401 Unauthorized response.

Top

Refresh the Token

If the token expires, and you receive a 401 Unauthorized response from a previously valid token, you can refresh the token using the refresh token that was provided with the initial authentication. Note, you still need to use the expired token in the authorization header to validate the refresh token:

curl -i -X POST --header "Authorization: Bearer 1f98dc780e22c751d8d6203d6c5c786e192136f1" \
  -d"refresh=2c9b3b2114bec3d2ffd12c9155a9639c0899aa25" http://localhost:8000/token/refresh

You can also send a JSON request like this as well:

curl -i -X POST --header "Authorization: Bearer 1f98dc780e22c751d8d6203d6c5c786e192136f1" \
  --header "Content-Type: application/json" \
  -d'{"refresh" : "2c9b3b2114bec3d2ffd12c9155a9639c0899aa25"}' \
  http://localhost:8000/token/refresh

And the response will be:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "token": "770e57fb47eede6eecbad24bf102d9fc54f81545",
    "refresh": "2c9b3b2114bec3d2ffd12c9155a9639c0899aa25",
    "expires": 1495057086
}

Note that the authentication token has been updated, but the refresh token has remained the same for future refresh requests. Now you can authenticate using the new authentication token:

curl -i -X POST --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/token

And you should receive a 200 OK response.

Top

Token Expiration

The API has two configuration settings that provides some control over the expiration of the authentication token. The default values are:

    'token_expires'       => 1800,
    'expiration_override' => true,

The token_expires setting is the TTL for the token in seconds, so in this case 1800 seconds, or 30 minutes. If this key is set to 0, then the tokens will not expire and can only be removed by revoking them. The expiration_override setting determines whether or not client applications can set their own token expiration value via the X-Token-Expires header. If this is set to true, then on authenticate and token refresh requests, a client application can pass a value to set a custom TTL for the token:

curl -i -X POST -d"username=admin&password=password" \
  --header "X-Token-Expires: 0" http://localhost:8000/auth

A value of 0 will set the token to live indefinitely, or at least until the token is specifically revoked.

Top

Revoke

If you want to end the user's session and revoke their access altogether, you can do so like this:

curl -i -X POST --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/revoke

Note that you still are require to pass the authentication token to verify which user session you want to terminate. When you do this, you will be ending the user's session and revoking their access until they authenticate again. The request will produce a 200 OK response. Any attempt to authenticate with the old token will result in a 401 Unauthorized response:

curl -i -X POST --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/token
HTTP/1.1 401 Unauthorized
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

Top

User Management

A basic level of user management is allowed with this API application. Besides the username and password fields, a user record also has an active field and a manage field. Both would contain either a 1 or a 0 for true or false, respectively. If a user's active flag is set to 0, it will disable them from successfully authenticating. The manage flag grants an authenticated user the ability to manage the other users. This includes registering, updating and deleting users.

Listing Users

To get a list of all of the users:

curl -i -X GET --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/users

Which returns:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "users": [
        {
            "id": "1",
            "username": "admin",
            "active": "1",
            "manage": "1"
        },
        {
            "id": "2",
            "username": "testuser",
            "active": "1",
            "manage": "0"
        },
        {
            "id": "3",
            "username": "testuser2",
            "active": "1",
            "manage": "1"
        }
    ]
}

To get data on a single user:

curl -i -X GET --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/users/1

Which returns:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "username": "admin",
    "active": 1,
    "manage": 1
}

Getting a Group of Users

You can pass an array of user_ids to the API to get a specific group of users based on those user IDs passed. You can either do it via a traditional GET query:

curl -g -i -X GET --header "Authorization: Bearer 4fa55a4486b31687a22f26901b2b684cdd798d9d" \
  "http://localhost:8000/users?user_ids[]=1&user_ids[]=3"

or by passing an URL encoded JSON string with e JSON content-type header:

curl -g -i -X GET --header "Authorization: Bearer 4fa55a4486b31687a22f26901b2b684cdd798d9d" \
  --header "Content-Type: application/json" \
  "http://localhost:8000/users?%7B%22user_ids%22%20%3A%20%5B1%2C%203%5D%7D"

Both requests will yield the same results, fetching only users #1 and #3:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "users": [
        {
            "id": "1",
            "username": "admin",
            "active": "1",
            "manage": "1"
        },
        {
            "id": "3",
            "username": "testuser2",
            "active": "1",
            "manage": "1"
        }
    ]
}

Top

Get User Count

You can get a count of the users registered with the application as well:

curl -i -X GET --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/users/count

Which would return the following response:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "user_count": 3
}

Top

Search and Sort Parameters

You can also use search and sort parameters for both listing users and also for getting a count of a subset of users. The basic search parameters as username, active and manage:

curl -i -X GET --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  "http://localhost:8000/users/count?username=test&active=1"

The above query will return a response with the user count of how many users have a username that start with test and are also active.

{
    "user_count": 2
}

The same parameters can be used for listing those users as well:

curl -i -X GET --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  "http://localhost:8000/users?username=test&active=1"

Which would return a response like this:

{
    "users": [
        {
            "id": 2,
            "username": "testuser",
            "active": 1,
            "manage": 1
        },
        {
            "id": 3,
            "username": "testuser2",
            "active": 1,
            "manage": 1
        }
}

Also for listing a large number of users, you can also pass the sort, limit and offset parameters to control the sorting order, the limit and the page offset:

curl -i -X GET --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545"  
  "http://localhost:8000/users?sort=id%20DESC&limit=5&offset=10"

Top

Registering a User

You can register a user by doing the following:

curl -i -X PUT --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  -d"username=testuser&password=12test34&active=1&manage=0" http://localhost:8000/register

The return response will contain data regarding the newly added user:

HTTP/1.1 201 Created
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 2,
    "username": "testuser",
    "active": 1,
    "manage": 0
}

Top

Updating a User

You can update a user like this:

curl -i -X POST --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  -d"username=testuser2&manage=1" http://localhost:8000/users/2

And the return response will be:

HTTP/1.1 200 Updated
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 2,
    "username": "testuser2",
    "active": 1,
    "manage": 1
}

Top

Deleting Users

Deleting a single user:

curl -i -X DELETE --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  http://localhost:8000/users/2

Which returns:

HTTP/1.1 204 Deleted
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

You can delete users in a group by sending over an array of user ids, like this:

curl -i -X DELETE --header "Authorization: Bearer 770e57fb47eede6eecbad24bf102d9fc54f81545" \
  -d"user_ids[]=2&user_ids[]=3&user_ids[]=4" http://localhost:8000/users

Which returns:

HTTP/1.1 204 Deleted
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

Top