NAME

Kernel::System::AccessToken::Storage::DB

DESCRIPTION

Authorization tokens database storage class.

PUBLIC INTERFACE

List()

Get a list of the access tokens.

    # returns all the access tokens.
    my $List = $AccessTokenObject->List();

    # returns all the access tokens for user-id X.
    my $List = $AccessTokenObject->List(Filters => {UserID => 'X'});

    # returns all the access tokens for user-id X or Y.
    my $List = $AccessTokenObject->List(Filters => {UserID => ['X', 'Y']});

    # returns all the access tokens for user-id (X or Y) and expires-time = 2018-02-18.
    my $List = $AccessTokenObject->List(Filters => {UserID => ['X', 'Y'], ExpiresTime => '2018-02-18'});

Returns

    C<undef> - in case any error occurs
    []       - in case no access token was found
    [
        Kernel::System::AccessToken::Token->new(),
        ...
    ]

Count()

Return the number of access-tokens that exists and match the passed filters.

    # Get the total of access-tokens.
    my $Count = $Storage->Count();

    # Get the total of access-tokens for the user-id X.
    my $Count = $Storage->Count( Filters => { UserID => 'X', }, );

Returns

    number - in case of success.
    C<undef> - in case any error occurs.

Get()

Get an access token by UUID or Token.

    # get by token.
    my $AccessToken = $AccessTokenObject->Get( Token => '...' );

    # get by uuid
    my $AccessToken = $AccessTokenObject->Get(UUID => '...');

Returns

    C<undef> - in case any error occurs
    empty K::S::AccessToken::Token - in case no record was found
    K::S::AccessToken::Token->new(
        UUID           => '...',
        UserID         => '...',
        UserType       => '...',
        CreateTime     => '...',
        ExpiresTime    => '...',
        LastAccessTime => '...',
    )

Create()

Create a new access token.

    my $AccessToken = $AccessTokenObject->Create(
        UUID        => '...',
        Token       => '...',
        UserID      => '...',
        UserType    => '...',
        ExpiresTime => '...',
    );

Returns

    Kernel::System::AccessToken::Token->new(
        UUID           => '...',
        Token          => '...',
        UserID         => '...',
        UserType       => '...',
        ExpiresTime    => '...',
        CreateTime     => '...',
        LastAccessTime => '...',
    );

    or C<undef> in case any error occurs.

Delete()

Delete access tokens.

    # delete all access tokens.
    my $Result = $Storage->Delete();

    # delete all access tokens where the expires time is lower than...
    my $Result = $Storage->Delete(
        Filters => {
            ExpiresTimeLower => '...', # optional
            UserID           => '...', # optional
            UUID             => '...', # optional
        },
    );

Returns

    1 - in case of success.
    C<undef> - in case any error occurs.

Update()

Update access tokens.

    # update create-time of all access tokens.
    my $Result = $Storage->Update(Data => {CreateTime => '2018-03-02'});

    # update last-access-time and create-time off all the access tokens for user-id X.
    my $Result = $Storage->Update(
        Filters => {UserID => 'X'},
        Data    => {LastAccessTime => '2018-03-02', CreateTime => '2018-03-01'}
    );

    # update last-access-time for uuid X.
    my $Result = $Storage->Update(
        Filters => {UUID           => 'X'},
        Data    => {LastAccessTime => '2018-04-01'},
    );

Returns

    1 - in case of success.
    C<undef> - in case any error occurs.

Generate()

Generate a new access-token (jwt-token) and saves it in the storage.

    my $AccessToken = $Storage->Generate(
        Username       => '...',  # (required)
        UserType       => '...',  # (required)
        Data           => {...},  # (optional)
        SessionMaxTime => 180,    # (optional) Expiration time in seconds, default: SessionMaxTime from config
    );

Returns

    C<undef> - in case any error occurs
    K::S::AccessToken::Token->new(
        UUID           => '...',
        UserID         => '...',
        UserType       => '...',
        CreateTime     => '...',
        ExpiresTime    => '...',
        LastAccessTime => '...',
    )

Decode()

Decode a jwt-token.

    my $TokenData = $AccessTokenObject->Decode(
        Token => '...' # jwt-token

        # claims (optional)
        VerifyIss => '',
        VerifyAud => '',
        VerifyExp => 0,
    );

Returns

    C<undef> - in case any error occurs
    hashref  - token data

Keys()

Returns the list of the current access-token keys, ordered by the most recent.

    my $Keys = $Storage->Keys();

Returns

    C<undef> - in case any error occurs
    []       - in case no key was found
    [
        Kernel::System::AccessToken::Key->new(...),
        ...
    ]

GenerateKey()

Generates a new access-token encrypt/decrypt key.

    my $Keys = $Storage->GenerateKey();

Returns

    C<undef> - in case any error occurs
    Kernel::System::AccessToken::Key->new(
        Value      => '...',
        CreateTime => '...',
    ),

DeleteKeys()

Deletes the given access-token keys.

    # Delete multiple keys.
    my $Result = $Storage->DeleteKeys( Key => ['...', '...'] );

    # Delete one key.
    my $Result = $Storage->DeleteKeys( Key => '...' );

    # Delete all the keys.
    my $Result = $Storage->DeleteKeys();
Returns

    1 - in case of success.
    C<undef> - in case any error occurs.

GetUserOnToken()

Returns the username that the token belongs to.

    my $UserLogin = $Self->GetUserOnToken(
        DecodedToken => { ... }     # decoded token
    );

PRIVATE INTERFACE

_Create()

Creates/adds a new access-token or key to the database.

    # Add a new token.
    my $AccessToken = $Storage->Create(
        Entity         => 'AccessToken',
        UUID           => '...',
        Token          => '...',
        UserID         => '...',
        UserType       => '...',
        ExpiresTime    => '...',
        CreateTime     => '...',
        LastAccessTime => '...',
    );

    # Add a new key.
    my $Key = $Storage->Create(
        Entity     => 'Key',
        Value      => '...',
        CreateTime => '...',
    );

Returns

    # access-token
    {
        UUID           => '...',
        Token          => '...',
        UserID         => '...',
        UserType       => '...',
        ExpiresTime    => '...',
        CreateTime     => '...',
        LastAccessTime => '...',
    };

    # key
    {
        Value      => '...',
        CreateTime => '...',
    };

    or C<undef> in case any error occurs.

_List()

Get a list of access-tokens or keys records.

    my $List = $Storage->List(
        Entity  => '...',
        Filters => {
            UUID             => '...' # optional
            UserID           => '...' # optional
            UserType         => '...' # optional
            ExpiresTime      => '...' # optional
            LastAccessTime   => '...' # optional
            ExpiresTimeLower => '...' # optional
        }
    );

Returns

    C<undef> - in case any error occurs
    []       - in case no data was found for the entity
    [
        {
            UUID           => '...',
            UserID         => '...',
            UserType       => '...',
            CreateTime     => '...',
            ExpiresTime    => '...',
            LastAccessTime => '...',
        },
        ...
    ]

_Get()

Get an access-token or key record.

    my $List = $Storage->Get(
        Entity => '...',
        UUID   => '...' # for access-token
        Value  => '...' # for key
    );

Returns

    C<undef> - in case any error occurs
    {}       - in case no data was found for the entity
    {...}    - inc case data was found

_Delete()

Delete access tokens from the database.

    # delete all access tokens.
    my $Result = $AccessTokenObject->Delete();

    # delete all access tokens according to the filters passed.
    my $Result = $AccessTokenObject->Delete(
        Filters => {
            ExpiresTimeLower => '...', # optional
            UserID           => '...', # optional
            UUID             => '...', # optional
        },
    );

Returns

    1 - in case of success.
    C<undef> - in case any error occurs.

_Update()

Update access tokens in the database.

    # update create-time of all access tokens.
    my $Result = $Storage->Update(Data => {CreateTime => '2018-03-02'});

    # update last-access-time and create-time off all the access tokens for user-id X.
    my $Result = $Storage->Update(
        Filters => {UserID => 'X'},
        Data    => {LastAccessTime => '2018-03-02', CreateTime => '2018-03-01'}
    );

Returns

    1 - in case of success.
    C<undef> - in case any error occurs.

_Count()

Return the number of records that exists in the storage that match the passed filters.

    # Get the total of access-tokens.
    my $Count = $Storage->Count( Entity => 'AccessToken', );

    # Get the total of access-tokens for the user-id X.
    my $Count = $Storage->Count( Entity => 'AccessToken', Filters => { UserID => 'X', }, );

Returns

    number - in case of success.
    C<undef> - in case any error occurs.

_IsValidEntity()

Checks if the passed entity is valid.

    my $Valid = $Storage->_IsValidEntity( Entity => '...' );

Returns

    C<undef> - in case is invalid.
    1        - in case is valid.

_FiltersSQLAndBinds()

Builds the SQL 'WHERE' clause and value binds based on the filters.

    # something like:
    my ($SQLWhere, $Binds) = $Self->_FiltersSQLAndBinds(
        Filters => {
            UserID      => 'X',
            ExpiresTime => '2018-02-18',
        },
    );
    # generates:
    $SQLWhere = (user_id = ?) AND (expires_time = ?)
    $Binds    = ['X', '2018-02-18']

    # it's possible to indicate which operator to use:
    my ($SQLWhere, $Binds) = $Self->_FiltersSQLAndBinds(
        Filters => {
            ExpiresTime => { '>=' => '2018-02-18'},
        },
    );
    # generates:
    $SQLWhere = (expires_time >= ?)
    $Binds    = ['2018-02-18']

Returns

    (string, arrayref)

_GetDBColumnMapForParams()

Get the mapping of params to database columns.

    # mapping for all params
    my $Map = $Self->_GetDBColumnMapForParams();

    # mapping only for the needed params
    my $Map = $Self->_GetDBColumnMapForParams(
        Want => [qw( UserType ExpiresTime )],
    );

Returns

    a map/dictionary with the param and respective column name.

_CacheType()

Returns the cache type.

_CacheTTL()

Returns the cache ttl.

_CacheDelete()

Deletes the entity cache. It detects if the operation was only for a record and delete only the 'Get' cache for that record, otherwise deletes everything.

    $Self->_CacheDelete(
        Entity  => 'AccessToken' or 'Key',
        Filters => {...}, # the filters passed to the update|delete operation
    );

_TokenEncryptKey()

Gets the access-token encryption/decryption secret from the config.

    my $Secret = $Self->_TokenSecret();

Returns

    String - in case the secret is set.
    dies in case the secret isn't set.

Facebook X LinkedIn