NAME

Kernel::System::AccessToken::Storage

DESCRIPTION

Authorization tokens base storage class.

PUBLIC INTERFACE

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()

Should save the entity in the storage.

    my $Result = $Storage->Create(
        Entity => '...',
        ...,
    );

Returns

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

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

    or C<undef> in case any error occurs.

List()

Should return a list for the entity available in the storage.

    my $List = $Storage->List(
        Entity  => '...',
        Filters => {...}
    );

Returns

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

ListActive()

Get a list of the active access tokens.

    # returns all the active access tokens.
    my $ListActive = $Storage->ListActive();

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

Returns

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

Delete()

Should delete entity records from the storage.

    my $Result = $Storage->Delete(
        Entity  => '...',
        Filters => {...}
    );

Returns

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

Update()

Should update entity records in the storage.

    my $Result = $Storage->Update(
        Entity  => '...',
        Filters => {...},
        Data    => {...}
    );

Returns

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

Count()

Should the number of records for the entity available in the storage.

    my $List = $Storage->Count(
        Entity  => '...',
        Filters => {...}
    );

Returns

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

CountActive()

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

CountMarkedForLimits()

Return the number of access-tokens that exists marked as 'IsCountedForLimits' and match the passed filters.

CountActiveMarkedForLimits()

Return the number of active access-tokens that exists marked as 'IsCountedForLimits' and match the passed filters.

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.

IsLocal()

Indicates if the tokens are managed by OTRS or an external service.

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

Returns

    1 - managed by OTRS
    0 - externally managed

GetUserOnToken()

Returns the username that the token belongs to.

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

AgentSessionPriorLimitIsReached()

Get the agent session limit prior warning message, if the limit is reached.

    my $PriorMessage = $AccessTokenObject->AgentSessionPriorLimitIsReached();

Returns the prior warning message or an empty string.

IsValid()

Checks if the the jwt-token is valid.

    my $AccessToken = $Storage->IsValid(
        UUID   => '...' # optional, OR
        Token  => '...' # optional (jwt-token)
    );

Returns

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

PRIVATE METHODS

_CheckFilters()

Checks if the given filters are supported.

    my $Secret = $Self->_CheckFilters(
        Filters => {
            UUID                  => '...', # optional
            Token                 => '...', # optional
            UserID                => '...', # optional
            UserType              => '...', # optional
            ExpiresTime           => '...', # optional
            ExpiresTimeLower      => '...', # optional
            ExpiresTimeGreater    => '...', # optional
            LastAccessTime        => '...', # optional
            LastAccessTimeLower   => '...', # optional
            LastAccessTimeGreater => '...', # optional
            IsCountedForLimits    => '...', # optional
            IsInteractive         => '...', # optional
            IsOneTimeOnly         => '...', # optional
            FromClient            => '...', # optional
        },
    );

Returns

    1        - in case all filters are valid
    C<undef> - in case any unknown filter was found.