OAuth2Token

OAuth2Token#

NAME#

Kernel::System::OAuth2Token - OAuth2Token lib

SYNOPSIS#

All OAuth2Token functions

PUBLIC INTERFACE#

new()#

create an object

my $OAuth2TokenObject = $Kernel::OM->Get('Kernel::System::OAuth2Token');

DataAdd()#

Add data to table.

my $Success = $OAuth2TokenObject->DataAdd(
    ID                         => '...',
    TokenConfigID              => '...',
    AuthorizationCode          => '...',
    Token                      => '...',
    TokenExpirationDate        => '...',
    RefreshToken               => '...',
    RefreshTokenExpirationDate => '...',
    ErrorMessage               => '...',
    ErrorDescription           => '...',
    ErrorCode                  => '...',
    CreateTime                 => '...',
    CreateBy                   => '...',
    ChangeTime                 => '...',
    ChangeBy                   => '...',
);

Returns:

my $Success = 1;

DataUpdate()#

Update data attributes.

my $Success = $OAuth2TokenObject->DataUpdate(
    ID                         => 1234,
    UserID                     => 1,

    # all other attributes are optional
    TokenConfigID              => '...',
    AuthorizationCode          => '...',
    Token                      => '...',
    TokenExpirationDate        => '...',
    RefreshToken               => '...',
    RefreshTokenExpirationDate => '...',
    ErrorMessage               => '...',
    ErrorDescription           => '...',
    ErrorCode                  => '...',
    CreateTime                 => '...',
    CreateBy                   => '...',
    ChangeTime                 => '...',
    ChangeBy                   => '...',
);

Returns:

my $Success = 1; # 1|0

DataGet()#

Get data attributes.

my %Data = $OAuth2TokenObject->DataGet(
    ID                         => '...', # optional
    TokenConfigID              => '...', # optional
    AuthorizationCode          => '...', # optional
    Token                      => '...', # optional
    TokenExpirationDate        => '...', # optional
    RefreshToken               => '...', # optional
    RefreshTokenExpirationDate => '...', # optional
    ErrorMessage               => '...', # optional
    ErrorDescription           => '...', # optional
    ErrorCode                  => '...', # optional
    CreateTime                 => '...', # optional
    CreateBy                   => '...', # optional
    ChangeTime                 => '...', # optional
    ChangeBy                   => '...', # optional
);

Returns:

my %Data = (
    ID                         => '...',
    TokenConfigID              => '...',
    AuthorizationCode          => '...',
    Token                      => '...',
    TokenExpirationDate        => '...',
    RefreshToken               => '...',
    RefreshTokenExpirationDate => '...',
    ErrorMessage               => '...',
    ErrorDescription           => '...',
    ErrorCode                  => '...',
    CreateTime                 => '...',
    CreateBy                   => '...',
    ChangeTime                 => '...',
    ChangeBy                   => '...',
);

DataListGet()#

Get list data with attributes.

my @Data = $OAuth2TokenObject->DataListGet(
    ID                         => '...', # optional
    TokenConfigID              => '...', # optional
    AuthorizationCode          => '...', # optional
    Token                      => '...', # optional
    TokenExpirationDate        => '...', # optional
    RefreshToken               => '...', # optional
    RefreshTokenExpirationDate => '...', # optional
    ErrorMessage               => '...', # optional
    ErrorDescription           => '...', # optional
    ErrorCode                  => '...', # optional
    CreateTime                 => '...', # optional
    CreateBy                   => '...', # optional
    ChangeTime                 => '...', # optional
    ChangeBy                   => '...', # optional
);

Returns:

my @Data = (
    {
        ID                         => '...',
        TokenConfigID              => '...',
        AuthorizationCode          => '...',
        Token                      => '...',
        TokenExpirationDate        => '...',
        RefreshToken               => '...',
        RefreshTokenExpirationDate => '...',
        ErrorMessage               => '...',
        ErrorDescription           => '...',
        ErrorCode                  => '...',
        CreateTime                 => '...',
        CreateBy                   => '...',
        ChangeTime                 => '...',
        ChangeBy                   => '...',
    },
    # ...
);

DataDelete()#

Remove data from table.

my $Success = $OAuth2TokenObject->DataDelete(
    ID                         => '...', # optional
    TokenConfigID              => '...', # optional
    AuthorizationCode          => '...', # optional
    Token                      => '...', # optional
    TokenExpirationDate        => '...', # optional
    RefreshToken               => '...', # optional
    RefreshTokenExpirationDate => '...', # optional
    ErrorMessage               => '...', # optional
    ErrorDescription           => '...', # optional
    ErrorCode                  => '...', # optional
    CreateTime                 => '...', # optional
    CreateBy                   => '...', # optional
    ChangeTime                 => '...', # optional
    ChangeBy                   => '...', # optional
);

Returns:

my $Success = 1;

DataSearch()#

Search for value in defined attributes.

my %Data = $OAuth2TokenObject->DataSearch(
    Search                     => 'test*test',
    ID                         => '...', # optional
    TokenConfigID              => '...', # optional
    AuthorizationCode          => '...', # optional
    Token                      => '...', # optional
    TokenExpirationDate        => '...', # optional
    RefreshToken               => '...', # optional
    RefreshTokenExpirationDate => '...', # optional
    ErrorMessage               => '...', # optional
    ErrorDescription           => '...', # optional
    ErrorCode                  => '...', # optional
    CreateTime                 => '...', # optional
    CreateBy                   => '...', # optional
    ChangeTime                 => '...', # optional
    ChangeBy                   => '...', # optional
);

Returns:

my %Data = (
    '1' => {
        ID                         => '...',
        TokenConfigID              => '...',
        AuthorizationCode          => '...',
        Token                      => '...',
        TokenExpirationDate        => '...',
        RefreshToken               => '...',
        RefreshTokenExpirationDate => '...',
        ErrorMessage               => '...',
        ErrorDescription           => '...',
        ErrorCode                  => '...',
        CreateTime                 => '...',
        CreateBy                   => '...',
        ChangeTime                 => '...',
        ChangeBy                   => '...',
    },
    # ...
);

InitConfig()#

init config for object

my $Success = $OAuth2TokenObject->InitConfig();

Returns:

my $Success = 1;

GenerateAuthorizationCodeRequestURL()#

Generates the URL used to request an authorization code for a token.

my $URL = $OAuth2TokenObject->GenerateAuthorizationCodeRequestURL(
    TokenConfigID => 3,
    UserID        => 1,
);

GetAuthorizationCodeRequestRedirectURL()#

Returns the redirect URL for retrieving an authorization code.

my $RedirectURL = $OAuth2TokenObject->GetAuthorizationCodeRequestRedirectURL();

GetAuthorizationCodeParameters()#

Retrieves authorization code parameters from web request parameters.

my %AuthorizationCodeParameters = $OAuth2TokenObject->GetAuthorizationCodeParameters(
    ParamObject => $ParamObject,
    UserID      => 2,
);

Returns:

my %AuthorizationCodeParameters = (
    TokenConfigID     => 7,
    AuthorizationCode => '...',
);

RequestTokenByAuthorizationCode()#

Requests a token by given authorization code.

my %Token = $OAuth2TokenObject->RequestTokenByAuthorizationCode(
    TokenConfigID     => 7,
    AuthorizationCode => '...',
    UserID            => 2,
);

Returns a full OAuth2Token record, as DataGet() would.

my %Token = (
    ID                         => 132,
    TokenConfigID              => 7,
    AuthorizationCode          => '...',
    Token                      => '...',
    TokenExpirationDate        => 3500,
    RefreshToken               => '...',
    RefreshTokenExpirationDate => 3500,
    Error                      => '',
    ErrorDescription           => '',
    ErrorCode                  => 0,
    CreateTime                 => '2020-08-24 10:00:00',
    CreateBy                   => 2,
    ChangeTime                 => '2020-08-24 10:00:00',
    ChangeBy                   => 2,
);

RequestTokenByRefreshToken()#

Requests a token by refresh token. The refresh token is stored in the token record.

my %Token = $OAuth2TokenObject->RequestTokenByRefreshToken(
    TokenConfigID => 7,
    UserID        => 2,
);

Returns a full OAuth2Token record, as DataGet() would.

my %Token = (
    ID                         => 132,
    TokenConfigID              => 7,
    AuthorizationCode          => '...',
    Token                      => '...',
    TokenExpirationDate        => 3500,
    RefreshToken               => '...',
    RefreshTokenExpirationDate => 3500,
    Error                      => '',
    ErrorDescription           => '',
    ErrorCode                  => 0,
    CreateTime                 => '2020-08-24 10:00:00',
    CreateBy                   => 2,
    ChangeTime                 => '2020-08-24 10:00:00',
    ChangeBy                   => 2,
);

HasTokenExpired()#

Checks if token has expired.

my $HasExpired = $OAuth2TokenObject->HasTokenExpired(
    TokenConfigID => 7,
    UserID        => 2,
);

Returns true value if token has expired.

HasRefreshTokenExpired()#

Checks if refresh token has expired (or is not present).

my $HasExpired = $OAuth2TokenObject->HasRefreshTokenExpired(
    TokenConfigID => 7,
    UserID        => 2,
);

Returns true value if refresh token has expired or is not present.

GetToken()#

Returns a valid token (not a token record), if possible.
Automatically retrieves a new token by refresh token if token has expired.

my $Token = $OAuth2TokenObject->GetToken(
    TokenConfigID => 7,
    UserID        => 2,
);

Returns a token, if possible.

GetTokenErrorMessage()#

Assembles the error message of a token, if any.

my $TokenErrorMessage = $OAuth2TokenObject->GetTokenErrorMessage(
    TokenConfigID => 7,
    UserID        => 2,
);

Returns string with error message, if any.

AssembleSASLAuthString()#

Assembles an SASL authentication string used to authenticate with an OAuth2 token.
Used  e.g. for IMAP, POP3 and SMTP.

See here:
https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#sasl-xoauth2
https://developers.google.com/gmail/imap/xoauth2-protocol#the_sasl_xoauth2_mechanism

my $SASLAuthString = $OAuth2TokenObject->AssembleSASLAuthString(
    Username    => 'user2',
    OAuth2Token => 'the token',
);

Returns base64 encoded authentication string for SASL.

_GetOrCreateIfNotExists()#

Initializes empty token record if it does not exist yet for the given token config ID.
Returns complete data of newly created token or of the one that already exists.

my %Token = $OAuth2TokenObject->_GetOrCreateIfNotExists(
    TokenConfigID => 7,
    UserID        => 2,
);

Returns a full OAuth2Token record, as DataGet() would.

my %Token = (
    ID                         => 132,
    TokenConfigID              => 7,
    AuthorizationCode          => '...',
    Token                      => '...',
    TokenExpirationDate        => 0,
    RefreshToken               => '...',
    RefreshTokenExpirationDate => 0,
    Error                      => '',
    ErrorDescription           => '',
    ErrorCode                  => 0,
    CreateTime                 => '2020-08-24 10:00:00',
    CreateBy                   => 2,
    ChangeTime                 => '2020-08-24 10:00:00',
    ChangeBy                   => 2,
);

_AssembleRequestData()#

Assembles request data for given request type of given token config.

my %RequestData = $OAuth2TokenObject->_AssembleRequestData(
    TokenConfigID => 7,
    RequestType   => 'TokenByAuthorizationCode', # or any types returned by _GetRequestTypes()
    UserID        => 2,
);

Returns hash ref with data for request:

my %RequestData = (
    client_id          => '...',
    client_secret      => '...',
    authorization_code => '...',
    # ...
);

_AssembleResponseDataFromWebRequest()#

Assembles response data from web request for given request type of given token config.

my %ResponseData = $OAuth2TokenObject->_AssembleResponseDataFromWebRequest(
    ParamObject   => $ParamObject,
    TokenConfigID => 7,
    RequestType   => 'TokenByAuthorizationCode', # or any types returned by _GetRequestTypes()
    UserID        => 2,
);

Returns hash ref with data of response:

my %ResponseData = (
    Token               => '...',
    TokenExpirationDate => '...',
    ErrorMessage        => '...',
    # ...
);

_AssembleResponseDataFromJSONString()#

Assembles response data from JSON string for given request type of given token config.

my %ResponseData = $OAuth2TokenObject->_AssembleResponseDataFromJSONString(
    JSONString    => '...',
    TokenConfigID => 7,
    RequestType   => 'TokenByAuthorizationCode', # or any types returned by _GetRequestTypes()
    UserID        => 2,
);

Returns hash ref with data of response:

my %ResponseData = (
    Token               => '...',
    TokenExpirationDate => '...',
    ErrorMessage        => '...',
    # ...
);

_GetRequestTypes()#

Returns the available request types.

my %RequestTypes = $OAuth2TokenObject->_GetRequestTypes();

Returns:

my %RequestTypes = (
    # request type => 1
    # ...
);

_CreateExpirationDateTimeObject()#

Creates an expiration DateTime object for a TTL (time to live).

my $DateTimeObject = $OAuth2TokenObject->_CreateExpirationDateTimeObject(
    StartDateTimeObject => $StartDateTimeObject,    # optional, offset for TTL. Current date/time will be used if omitted.
    TTL                 => 3600,                    # seconds (>= 0)
);

Returns DateTime object.
Contents