########### OAuth2Token ########### **** NAME **** Kernel::System::OAuth2Token - OAuth2Token lib ******** SYNOPSIS ******** All OAuth2Token functions **************** PUBLIC INTERFACE **************** new() ===== create an object .. code-block:: perl my $OAuth2TokenObject = $Kernel::OM->Get('Kernel::System::OAuth2Token'); DataAdd() ========= Add data to table. .. code-block:: perl my $Success = $OAuth2TokenObject->DataAdd( ID => '...', TokenConfigID => '...', AuthorizationCode => '...', Token => '...', TokenExpirationDate => '...', RefreshToken => '...', RefreshTokenExpirationDate => '...', ErrorMessage => '...', ErrorDescription => '...', ErrorCode => '...', CreateTime => '...', CreateBy => '...', ChangeTime => '...', ChangeBy => '...', ); Returns: .. code-block:: perl my $Success = 1; DataUpdate() ============ Update data attributes. .. code-block:: perl 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: .. code-block:: perl my $Success = 1; # 1|0 DataGet() ========= Get data attributes. .. code-block:: perl 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: .. code-block:: perl my %Data = ( ID => '...', TokenConfigID => '...', AuthorizationCode => '...', Token => '...', TokenExpirationDate => '...', RefreshToken => '...', RefreshTokenExpirationDate => '...', ErrorMessage => '...', ErrorDescription => '...', ErrorCode => '...', CreateTime => '...', CreateBy => '...', ChangeTime => '...', ChangeBy => '...', ); DataListGet() ============= Get list data with attributes. .. code-block:: perl 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: .. code-block:: perl my @Data = ( { ID => '...', TokenConfigID => '...', AuthorizationCode => '...', Token => '...', TokenExpirationDate => '...', RefreshToken => '...', RefreshTokenExpirationDate => '...', ErrorMessage => '...', ErrorDescription => '...', ErrorCode => '...', CreateTime => '...', CreateBy => '...', ChangeTime => '...', ChangeBy => '...', }, # ... ); DataDelete() ============ Remove data from table. .. code-block:: perl 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: .. code-block:: perl my $Success = 1; DataSearch() ============ Search for value in defined attributes. .. code-block:: perl 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: .. code-block:: perl my %Data = ( '1' => { ID => '...', TokenConfigID => '...', AuthorizationCode => '...', Token => '...', TokenExpirationDate => '...', RefreshToken => '...', RefreshTokenExpirationDate => '...', ErrorMessage => '...', ErrorDescription => '...', ErrorCode => '...', CreateTime => '...', CreateBy => '...', ChangeTime => '...', ChangeBy => '...', }, # ... ); InitConfig() ============ init config for object .. code-block:: perl my $Success = $OAuth2TokenObject->InitConfig(); Returns: .. code-block:: perl my $Success = 1; GenerateAuthorizationCodeRequestURL() ===================================== .. code-block:: perl Generates the URL used to request an authorization code for a token. my $URL = $OAuth2TokenObject->GenerateAuthorizationCodeRequestURL( TokenConfigID => 3, UserID => 1, ); GetAuthorizationCodeRequestRedirectURL() ======================================== .. code-block:: perl Returns the redirect URL for retrieving an authorization code. my $RedirectURL = $OAuth2TokenObject->GetAuthorizationCodeRequestRedirectURL(); GetAuthorizationCodeParameters() ================================ .. code-block:: perl Retrieves authorization code parameters from web request parameters. my %AuthorizationCodeParameters = $OAuth2TokenObject->GetAuthorizationCodeParameters( ParamObject => $ParamObject, UserID => 2, ); Returns: my %AuthorizationCodeParameters = ( TokenConfigID => 7, AuthorizationCode => '...', ); RequestTokenByAuthorizationCode() ================================= .. code-block:: perl 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() ============================ .. code-block:: perl 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, ); RequestTokenByClientCredentials() ================================= .. code-block:: perl Requests a token by client credentials. The refresh token is stored in the token record. my %Token = $OAuth2TokenObject->RequestTokenByClientCredentials( TokenConfigID => 7, UserID => 2, ); Returns a full OAuth2Token record, as DataGet() would. my %Token = ( ID => 132, TokenConfigID => 7, AuthorizationCode => '...', # not relevant for auth flow ClientCredentials Token => '...', TokenExpirationDate => 3500, RefreshToken => '...', # not relevant for auth flow ClientCredentials RefreshTokenExpirationDate => 3500, # not relevant for auth flow ClientCredentials Error => '', ErrorDescription => '', ErrorCode => 0, CreateTime => '2020-08-24 10:00:00', CreateBy => 2, ChangeTime => '2020-08-24 10:00:00', ChangeBy => 2, ); HasTokenExpired() ================= .. code-block:: perl Checks if token has expired. my $HasExpired = $OAuth2TokenObject->HasTokenExpired( TokenConfigID => 7, UserID => 2, ); Returns true value if token has expired. HasRefreshTokenExpired() ======================== .. code-block:: perl 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() ========== .. code-block:: perl Returns a valid token (not a token record), if possible. Automatically retrieves a new token by refresh token if token has expired and refresh token is available. my $Token = $OAuth2TokenObject->GetToken( TokenConfigID => 7, UserID => 2, ); Returns a token, if possible. GetTokenErrorMessage() ====================== .. code-block:: perl 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() ======================== .. code-block:: perl 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() ========================= .. code-block:: perl 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() ====================== .. code-block:: perl 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() ===================================== .. code-block:: perl 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() ===================================== .. code-block:: perl 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() ================== .. code-block:: perl Returns the available request types. my %RequestTypes = $OAuth2TokenObject->_GetRequestTypes(); Returns: my %RequestTypes = ( # request type => 1 # ... ); _CreateExpirationDateTimeObject() ================================= .. code-block:: perl 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.