NAME

Kernel::System::OIDC::Base – Interface with Keycloak REST API

DESCRIPTION

Functions for REST communication with Keycloak.

PUBLIC INTERFACE

MethodParamValidationSchema()

Default parameter validation schema.

SyncRoles()

Sync OTRS roles to the Keycloak client roles (OTRS local roles are not modified).

    my $Result = $Self->SyncRoles();

Returns

    $Result = {
        Success => 0,
        Data    => [], # what it could do until the error
        Message      => '...',
        ErrorMessage => '...',
        ErrorCode    => '...',
    };

CacheType()

Returns the cache type.

IsTokenValid()

Checks if the token is valid by trying to decode it.

    my $DecodedToken = $Self->IsTokenValid( Token => '...' );

Returns

    decoded token - if valid
    undef         - not valid

TokenCreate()

Creates user token (Keycloak session), based on the user login and password.

    my $Token = $Self->TokenCreate(
        UserLogin => 'jdoe',        # (required) user login
        Password  => 'Pa$$word',    # (required) password
    );

Returns

    $Token = 'yJhbGciOiJSUzI1NiIsI...'; # or undef in the case of error

GetUserOnToken()

Returns the username that the token belongs to.

    my $UserLogin = $Self->GetUserOnToken(
        Token => '...' # or { ... }     # jwt-token
                                        # or decoded token
    );

Returns the UserLogin if the token is valid, undef if not.

GetTokenRolesArray()

Returns an ArrayRef with the roles array present in the given token. Returns [] if not found and undef in error scenarios.

    my $Roles = $Self->GetTokenRolesArray(
        DecodedToken => $DecodedToken,
    );

HasAccess()

Checks if user DecodedToken has required role (determines if user is agent or customer user).

    my $Access = $Self->HasAccess(
        DecodedToken => {
            ...
            "resource_access" => {
                "otrs-client-dev" => {
                    "roles" => [
                        "Administrator",
                        "Agent",
                        ...
                    ],
                },
            },
            ...
        },
    );

Returns

    $Access = 1;    # or undef

ModuleInfo()

Returns a string with the module configuration.

GetSyncRolesStatus()

Get sync status for role sync from system data.

    my %SystemDataSync = $Self->GetSyncRolesStatus()

returns

    %SyncRolesStatus = (
        Scheduled   => '2025-01-01 00:00:01',
        Last        => '2025-01-01 00:00:01'
        ...
    );

TriggerSyncRolesJob()

Trigger the role synchronization process.

SyncRolesJobCompleted()

Deletes from the system data the flag indicated that the sync job was scheduled.

RequiredConfigAttributes

Returns an array with the required attributes that need to be set for the module/object to work correctly.

InGoodState

Checks if the module/object is in a good state to be used.

Returns

    1 - yes
    0 - no, config missing

PRIVATE METHODS

_APIRequest()

Perform API request.

    my $Response = $Keycloak->_APIRequest(
        Method => 'Get',                      # (optional) default 'GET'
        URL    => 'http://localhost',         # (optional) full url
        Path   => '/admin/realms/agent/user', # (optional) partial url, host will be added, ignored if URL is given
        Query  => {                           # (optional)
        },
        Headers => {                          # (optional)
            Authorization => '',
            ...
        },
        SkipAuth     => 0,                    # (optional) default 0
        JSONBody     => {},                   # (optional)
        FormBody     => {},                   # (optional)
        ErrorMessage => '...'                 # (required)
        HandleError  => 1|0                   # (optional) default 1
    );

Returns

    undef                   - error
    Mojo::Message::Response - success

_APIRequestResponseData()

Performs an API request and returns the json body.

    my $JSONResponse = $Self->_APIRequestResponseData(
        Method => 'Get',                      # (optional) default 'GET'
        URL    => 'http://localhost',         # (optional) full url
        Path   => '/admin/realms/agent/user', # (optional) partial url, host will be added, ignored if URL is given
        Query  => {                           # (optional)
        },
        Headers => {                          # (optional)
            Authorization => '',
            ...
        },
        SkipAuth     => 0,                    # (optional) default 0
        JSONBody     => {},                   # (optional)
        FormBody     => {},                   # (optional)
        ErrorMessage => '...'                 # (required)
    );

Returns

    undef               - error
    json parsed to perl - success

_GetAccessToken()

Requests for an API access token.

    my $AccessToken = $Self->_GetAccessToken();

Returns

    $AccessToken = '...';

_LogError()

Logs an error given in $Param{Message}.

    $Self->_LogError( Message => 'some error' );

_GetConfigValue()

Returns the config value for the given key.

    my $Value = $Self->_GetConfigValue( 'config-key' );

_CheckRoleCompatibility()

Returns a bool whether to skip a user due to role mismatch.

    my $RoleCompatibility = $Self->_CheckRoleCompatibility(
        OIDCUser  => $OIDCUser,
        UserLogin => $User->{UserLogin},
        Required  => 'Agent',       # e.g. 'Agent' or 'Customer User'
    );

    # 1 - it is the same user, should be updated
    # 0 - there is diferent role(s), skip it