https://github.com/verzth/tcx
auth authentication authorization laravel laravel-auth laravel-authentication laravel-authorization laravel-framework
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/verzth/tcx
- Owner: verzth
- License: mit
- Created: 2018-07-11T07:37:01.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2020-05-04T07:46:15.000Z (about 5 years ago)
- Last Synced: 2025-01-10T15:43:22.189Z (4 months ago)
- Topics: auth, authentication, authorization, laravel, laravel-auth, laravel-authentication, laravel-authorization, laravel-framework
- Language: PHP
- Size: 59.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TCX v4.0.0 - Authentication Module for Client-Server Transaction (One Way - Two Way).
### TCX is authentication module to secure API Server.
It's adapt OAuth2 scheme, but it use more simplify scheme which provide authentication for client-server without need to define scopes.
#### Dependencies
Laravel **>= 5.6**
#### How to Install
```
composer require verzth/tcx
```
#### How to Use
1. Add our ServiceProvider on your **config/app.php**.
```php
return [
//...
//..
//.
'providers' => [
// ...
Verzth\TCX\TCXServiceProvider::class,
...
]
//.
//..
//...
];
```
2. Add TCX Middleware in your **app/Http/Kernel.php**.
- In every request.
```php
$middleware = [
//...
\Verzth\TCX\Middleware\TCXMiddleware::class,
//...
];
```
or
- In your API group middleware only.
```php
$middlewareGroups = [
//...
'api' => [
//...
\Verzth\TCX\Middleware\TCXMiddleware::class,
//...
]
//...
];
```
or
- In your route middleware, and you can add manually on your route.
```php
$routeMiddleware = [
//...
'tcx' => \Verzth\TCX\Middleware\TCXMiddleware::class,
//...
];
```
3. Publish our vendor with artisan command.
```shell script
php artisan vendor:publish --provider=Verzth\TCX\TCXServiceProvider
```
4. Migrate our TCX DB. After migrate it, you will get 3 tables (tcx_applications, tcx_accesses, tcx_mkas).
```shell script
php artisan migrate
```
5. Refresh the autoload with below command.
```shell script
composer dump-autoload
```
6. We provide seeder to generate sample data.
Simply put below code to file database/seeds/DatabaseSeeder.php, inside run() function.
```php
$this->call(TCXApplicationsTableSeeder::class);
```
then run below script on your shell/command prompt.
```shell script
composer db:seed
```
7. Or just run below script (skip step 6) to generate the sample data.
```shell script
php artisan db:seed --class=TCXApplicationsTableSeeder
```
#### Implementation
1. Authentication Type, TCX support three ways authentication type:
- **One Way Transaction Code (OWTC)**: Client only need to use **app_id** and **app_public** to access Server APIs.
- **Two Way Transaction Code (TWTC)**: Client has to use **app_id** and **app_public** to get access token, then it can be used to access APIs.
- **Free Transaction Code (FTC)**: Client use master token to access APIs, without need to request token for every requests, it's specially design to by pass **TWTC** authentication. You need to
generate Master token manually.
To specify authentication for each APIs assign parameter in the middleware, use **or (|)** sign to specify multiple authentication or use
**all** to support all type (Supported type : **all**, **owtc**, **twtc**). By default, TCX will support all authentication if you didn't
specifying supported type.
Client need to specify type by sending **X-TCX-TYPE** header in every APIs request.
2. How to generate credentials:
- **app_pass** or **X-TCX-APP-PASS**, it can be generate by hashing plain of joined token (param, time, or none), application public key,
and client dynamic token with SHA1. Client need to append the given dynamic token to hash result by splitting with **colon (:)**
symbol, then encrypt it with base64.
- Param base
Sample Parameter:
```
abc=123
_xyz=789
foo=bar
def=456
bar=ghi
```
Expected Token:
```
_xyz=789&abc=123&bar=ghi&def=456&foo=bar
```
- Time base
```
tcx_datetime=YYYYMMDDHHmmss
```
Sample
```
tcx_datetime=20181230235959 // For 23:59:59, 30 December 2018
```
- None, just using application password and client dynamic token.
- **token** or **X-TCX-TOKEN**, it's provided when Client authorizing to server, but you need to encrypt it with base64.
3. Authentication Headers.
- Type **OWTC**:
- **'X-TCX-TYPE'**: **'OWTC'**.
- **'X-TCX-APP-ID'**: Client ID.
- **'X-TCX-APP-PASS'**: Client Password.
- Type **TWTC**:
- **'X-TCX-TYPE'**: **'TWTC'**.
- **'X-TCX-APP-ID'**: Client ID.
- **'X-TCX-APP-PASS'**: Client Password.
- **'X-TCX-TOKEN'**: Access Token, obtained by doing authorization.
- Type **FTC**:
- **'X-TCX-TYPE'**: **'FTC'**.
- **'X-TCX-APP-ID'**: Client ID.
- **'X-TCX-APP-PASS'**: Client Password.
- **'X-TCX-TOKEN'**: Master Access Token.
4. Authorization Routes, TCX provide some routes which is can be used to get access token in TWTC type:
- **/tcx/authorize**:
- METHOD: POST
- Params:
* **app_id**: Client application id.
* **app_pass**: Client password.
Sample **Fail** response
```
{
"status": 0,
"status_number": "002",
"status_code": "TCXAFX",
"status_message": "Authentication Failed"
}
```
Sample **Success** response
```
{
"status": 1,
"status_number": "701",
"status_code": "TCXSSS",
"status_message": "Authentication Success",
"data": {
"token": "tfDBOa6q3PPTJFd0A8HWftw2sXMV1b5ue6v0intK",
"refresh": "fR0HLeL5qk0ZdtthI2ZsQLZx8BHEP2dSnVaQqkF5",
"expired_at": "2018-10-16 13:31:43"
}
}
```
- **/tcx/reauthorize**:
Refresh token can be used to refresh your existing token, you can pass it to this service and your existing token
will be extended. Service will reply new refresh token for your existing token to be used in next refresh.
- METHOD: POST
- Params:
* **app_id**: Client application id.
* **token**: Refresh Token.
Sample **Fail** response
```
{
"status": 0,
"status_number": "002",
"status_code": "TCXAFX",
"status_message": "Authentication Failed"
}
```
Sample **Success** response
```
{
"status": 1,
"status_number": "701",
"status_code": "TCXSSS",
"status_message": "Token refreshed",
"data": {
"refresh": "04ITeVxWINOesyHH5Sxx57rN5uAW0ltCWN0cENxD",
"expired_at": "2018-10-16 13:36:42"
}
}
```
5. Response Status.
| Status | Number | Code | Message | Note |
| :----: | :----: | :---: | ------- | -------- |
| 0 | 70FF000 | TCXREQ | TCX Authentication Required | Provide Authentication Header |
| 0 | 20FF001 | TCXRJC | TCX Authentication Rejected | X-TCX-Type not supported or disabled |
| 0 | 40FF002 | TCXAFX | TCX Authentication Failed | X-TCX-App-ID not found, invalid, or inactive |
| 0 | 50FF003 | TCXPFX | TCX Pass did not match | X-TCX-App-Pass not passed, crosscheck point 2 |
| 0 | 50FF004 | TCXMKF | TCX Master Key did not valid | Check the master access key (Only FTC) |
| 0 | 50FF005 | TCXTFX | TCX Token did not valid | Check the access key (Only TWTC) |
Sample Response:
```
{
"status": 0,
"status_code": "TCXREQ",
"status_number": "70FF000",
"status_message": "TCX Authentication Required"
}
```