/ 
WWW-Suffit-API-1.03
River stage zero No dependents
/ WWW::Suffit::Server::API::Auth

NAME

WWW::Suffit::Server::API::Auth - The authentication and authorization Suffit API controller

SYNOPSIS

use WWW::Suffit::Server::API::Auth;

DESCRIPTION

The authentication and authorization Suffit API controller

METHODS

List of authorization/authentication methods

authorize

$c->routes->post('/authorize')->to('API::Auth#authorize'
  => {token_type => 'session'});
$c->routes->post('/authorize')->to('API::Auth#authorize'
  => {token_type => 'access'});
$c->routes->post('/authorize')->to('API::Auth#authorize'
  => {token_type => 'api'});

The authorization controller by stashed parameters

Options:

skip_authdb_connect
skip_authdb_connect => 1

This option disables connection to authorization database

token_type
token_type => 'access'

This option is required and sets the token type: access, session or api

See "POST /authorize"

is_authorized

my $authorized = $c->routes->under('/api')->to('API::Auth#is_authorized')
     ->name('api');

The API Authorization checker. If use `init_api_routes` startup option then this route will be exists by default. To get access to this route use:

my $authorized = $r->lookup('api');

API METHODS

List of API methods

POST /api/authorize

This method performs authentication and authorization on the Suffit API server, then returns the access token

# curl -v -X POST \
  -H "Accept: application/json" \
  -d '{
    "username": "test",
    "password": "test",
    "encrypted": false,
    "remember": false,
    "cachekey": ""
  }' \
  https://localhost:8695/api/authorize

# curl -v -X POST \
  -H "Accept: application/json" \
  -F username=test -F password=test \
  https://localhost:8695/api/authorize

> POST /authorize HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: application/json
> Content-Length: 248
> Content-Type: multipart/form-data; boundary=-----6a21ca7cea8dc981
>
< HTTP/1.1 200 OK
< Date: Tue, 13 Aug 2024 14:42:56 GMT
< Content-Type: application/json;charset=UTF-8
< Content-Length: 635
< Server: WWW::Suffit/1.00
<
{
  "cachekey": "97vyZgPzskPG",
  "clientid": "f459f12619c961122450ae5883e44a60",
  "code": "E0000",
  "datetime": "2024-08-13T14:42:56Z",
  "elapsed": 0.230106,
  "encrypted": false,
  "expires": "2024-08-14T14:42:56Z",
  "jti": "oWwGYKT2MdKj-xVvF9s9",
  "message": "The user is successfully authorized",
  "referer": "",
  "status": true,
  "token": "ey...8o",
  "type": "access",
  "user": {
    "algorithm": "SHA256",
    "attributes": "",
    "comment": "Test user for internal testing only",
    "created": 1678741533,
    "email": "test@owl.localhost",
    "email_md5": "163e50783979333ebae6fd63b2d96d16",
    "expires": 1723560176,
    "flags": 31,
    "groups": [
      "user"
    ],
    "name": "Test User",
    "not_after": 0,
    "not_before": 1695334721,
    "public_key": "-----BEGIN RSA PUBLIC KEY-----...",
    "role": "Test user",
    "uid": 3,
    "username": "test"
  }
}

ERROR CODES

List of authentication and authorization Suffit API error codes

 API   | HTTP  | DESCRIPTION
-------+-------+-------------------------------------------------
 E1000   [403]   Access denied. No token/session exists
 E1001   [403]   Access denied. JWT error
 E1002   [403]   Access denied. The token has been revoked
 E1003   [ * ]   Access denied. Session is not authorized
 E1004   [ * ]   Access denied by realm restrictions
 E1005   [500]   The authorization database is not ready
 E1006   [500]   Can't connect to authorization database
 E1007   [---]   Reserved
 E1008   [---]   Reserved
 E1009   [---]   Reserved
 E1010   [---]   Reserved
 E1011   [---]   Reserved
 E1012   [---]   Reserved
 E1013   [---]   Reserved
 E1014   [---]   Reserved
 E1015   [---]   Reserved
 E1016   [---]   Reserved
 E1017   [---]   Reserved
 E1018   [---]   Reserved
 E1019   [---]   Reserved
 E1020   [400]   Incorrect token type
 E1021   [401]   No username specified
 E1022   [401]   No password specified
 E1023   [500]   RSA decode error
 E1024   [500]   Can't JWT generate
 E1025   [500]   Can't token store to database
 E1026   [---]   Reserved
 E1027   [---]   Reserved
 E1028   [---]   Reserved
 E1029   [---]   Reserved

* -- this code will be defined later on the interface side

See also list of common Suffit API error codes in "ERROR CODES" in WWW::Suffit::API

HISTORY

See Changes file

TO DO

See TODO file

SEE ALSO

WWW::Suffit::Server

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2024 D&D Corporation. All Rights Reserved

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See LICENSE file and https://dev.perl.org/licenses/