README

An extension to handle signed access token authentication via JSON RPC 2.0.

This library interfaces with yii2-json-rpc-2.0 to provide the JSON RPC 2.0 communication in your controller and namshi/jose to generate signed JWS tokens.

For license information check the LICENSE-file.

Installation

The preferred way to install this extensions is through composer.

Either run

php composer.phar require --prefer-dist thamtech/yii2-jsonrpc-jwsauth

or add

"thamtech/yii2-jsonrpc-jwsauth": "*"

to the require section of your composer.json file.

Integration

Generate a kepair using OpenSSL and store the keys in public.pem and private.pem.

Add the JwsManager application component in your site configuration:

return [
  'components' => [
    'jwsManager' => [
      'class' => 'thamtech\jwsauth\components\JwsManager',
      'pubkey' => '@app/config/keys/jwsauth/public.pem',
      'pvtkey' => '@app/config/keys/jwsauth/private.pem',
      
      // The settings below are optional. Defaults will be used if not set here.
      //'encoder' => 'Namshi\JOSE\Base64\Base64UrlSafeEncoder',
      //'refreshExp' => '24 hours',
      //'exp' => '1 hour',
      //'alg' => 'RS256',
      //'jwsClass' => 'Namshi\JOSE\SimpleJWS',
    ],
  ]
]

Create a UserController in your application:

class UserController extends \thamtech\jwsauth\controllers\UserController
{
  // parent class provides actionAuthenticate($username, $passwrd)
  // and actionRefreshToken()
  
  // You may add your own additional methods to provide additional user
  // management services such as registration, password changes, etc.
}

Update your User model to implement \thamtech\jwsauth\models\IdentityInterface instead of \yii\web\IdentityInterface, and use the SimpleUserTrait:

class User extends \yii\base\Object implements \thamtech\jwsauth\models\IdentityInterface
{
  use SimpleUserTrait;
  
  public $id;
  public $username;
  
  // You must still implement all methods required by \yii\web\IdentityInterface
  // since \thamtech\jwsauth\models\IdentityInterface extends
  // \yii\web\IdentityInterface
}

Add the JsonRpcAuth filter on any \JsonRpc2\Controller you would like jwsauth-authenticated users to access:

public function behaviors()
{
  return [
    'authenticator' => [
      'class' => \thamtech\jwsauth\filters\auth\JsonRpcAuth::className(),
      'except' => ['public-method-1', 'public-method-2'],
    ],
  ];
}

Client-Side Usage

Make a JSON RPC request to the authenticate method passing in a username and password.

http://yoursite/user

with data

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "authenticate",
  "params": {
    "username": "YOUR-USERNAME",
    "password": "YOUR-PASSWORD"
  }
}

and a successful response will be something like this

{"jsonrpc":"2.0","id":1,"result":{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJpZCI6MT-TRIMMED_FOR_BREVITY"}}

Make a JSON RPC request to any controller/method requiring authentication using the token provided in the previous step:

http://yoursite/protected-controller

with data

{
  "jsonrpc": "2.0",
  "id": 2,
  "auth": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJpZCI6MT-TRIMMED_FOR_BREVITY",
  "method": "access-sensitive-data",
  "params": {"id": 27}
}

Expiration and Refreshing Tokens

When the token expires (after 1 hour by default), you may refresh the token without requiring the user to re-authenticate with username and password. This is allowed up to the refresh expiration of a token (24 hours by default).

If you have a valid token and make an authenticated request but receive a result like the following:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32652,
    "data": null,
    "message": "Invalid or expired token"
  }
}

then your next step is to try to refresh the token:

http://yoursite/user

with data

{
  "jsonrpc": "2.0",
  "id": 4,
  "auth": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJpZCI6MT-TRIMMED_FOR_BREVITY",
  "method": "refresh-token"
}

The response will either contain a new token which you may continue using normally:

{"jsonrpc":"2.0","id":4,"result":{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJpZCI6MT-TRIMMED_FOR_BREVITY"}}

Or an indication that the token could not be refreshed:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32652,
    "data": null,
    "message": "expired; user must reauthenticate"
  }
}

If the token could not be refreshed, then you will need to:

Ask the user to re-login with their username and password
Use the "authenticate" method in Step 1 of the Client-Side Usage section above to get a new auth token.
Continue making authenticated requests with the new token.

Advanced Usage

You do not have to use SimpleUserTrait in your User identity. It is merely a convenience for most use cases. You are free to implement your own getAuthKey() and findIdentityByAccessToken() methods directly in your User identity class in a way that better suits your application's needs.

Rather than instantiating a UserController as a sublcass, you could refer to \thamtech\jwsauth\controllers\UserController directly in a controller map:

[
  'controllerMap' => [
    // declares "login" controller using a class name
    'login' => 'thamtech\jwsauth\controllers\UserController',
  ],
]

thamtech / yii2-jsonrpc-jwsauth

Maintainers

Details

README

Installation

Integration

Client-Side Usage

Expiration and Refreshing Tokens

Advanced Usage

See Also