foliolib.folio.api.loginKeycloak.Loginkeycloak

class foliolib.folio.api.loginKeycloak.Loginkeycloak(tenant: str)

Bases: foliolib.folio.FolioApi

Mod Login Keycloak API

Base class of the Folio API

Parameters: tenant (str) – Tenant id

Methods

`checkcredentialsexistence`(**kwargs)	Returns single property 'credentialsExist' with true, if user has local password
`createcredentials`(loginCredentials)	Add a new login to the system.
`createresetpasswordaction`(passwordCreateAction)	Saves password reset action to storage
`deletecredentials`(**kwargs)	Delete credentials for user
`deletelogevent`(eventId)	Saves received event into the storage
`getlogevents`(**kwargs)	Returns a list of events retrieved from storage
`getloginattempts`(userId)	Get login attempts for a single user
`getpasswordactionbyid`(actionId)	Retrieves action record by id
`login`(loginCredentials)	Get a new login token
`loginwithexpiry`(loginCredentials)	Get an expiring refresh and access token
`logout`()	Logs the user out on their current device
`logoutall`()	Logs the user out on all of their devices
`refreshtoken`()	Get a new refresh and access token
`resetpassword`(passwordResetAction)	Resets password for user in record and deletes action record
`savelogevent`(logEvent)	Saves received event into the storage
`token`(**kwargs)	Get a new login token from the authorization code
`updatecredentials`(updateCredentials)	Self-update existing credentials.
`validatepasswordrepeatability`(password)	Validate password for repeatability

checkcredentialsexistence(**kwargs)

Returns single property ‘credentialsExist’ with true, if user has local password

GET /authn/credentials-existence

Keyword Arguments: userId (str) – User identifier
Returns: See Schema below.
Return type: dict
Raises: OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "credentialsExistence.json",
    "title": "Credential Existence Schema",
    "description": "Credentials existence response",
    "type": "object",
    "properties": {
        "credentialsExist": {
            "type": "boolean",
            "description": "True if user has local password"
        }
    },
    "required": [
        "credentialsExist"
    ]
}

createcredentials(loginCredentials)

Add a new login to the system.

POST /authn/credentials

Parameters

loginCredentials (dict) – See Schema below.

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "loginCredentials.json",
    "title": "Login Credentials Schema",
    "description": "An entity that describes the basic credentials for a user to log on to the system",
    "type": "object",
    "properties": {
        "username": {
            "description": "Username in the system, case insensitive",
            "type": "string"
        },
        "userId": {
            "description": "Unique user id",
            "type": "string"
        },
        "password": {
            "description": "User password",
            "type": "string"
        }
    },
    "required": [
        "password"
    ]
}

createresetpasswordaction(passwordCreateAction)

Saves password reset action to storage

POST /authn/password-reset-action

Parameters

passwordCreateAction (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "passwordCreateAction.json",
    "title": "Password Create Action Schema",
    "description": "A password create action response",
    "type": "object",
    "properties": {
        "id": {
            "description": "ID of the password reset action received in the API request",
            "type": "string"
        },
        "userId": {
            "description": "User ID to register password reset action",
            "type": "string"
        },
        "expirationTime": {
            "description": "password expiration time",
            "type": "string",
            "format": "date-time"
        }
    },
    "required": [
        "id",
        "userId",
        "expirationTime"
    ]
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "passwordCreateResponse.json",
    "title": "Password Create Action Response Schema",
    "description": "Response entity to create a new password change action",
    "type": "object",
    "properties": {
        "passwordExists": {
            "description": "Check if the user has an existing password or credential",
            "type": "boolean"
        }
    }
}

deletecredentials(**kwargs)

Delete credentials for user

DELETE /authn/credentials

Keyword Arguments

userId (str) – User identifier

Raises

OkapiRequestNotFound – Error response in JSON format for validation errors.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

deletelogevent(eventId)

Saves received event into the storage

DELETE /authn/log/events/{eventId}

Parameters

eventId (str) – Event Identifier

Raises

OkapiRequestNotFound – Error response if entity is not found by id (in json format)
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

getlogevents(**kwargs)

Returns a list of events retrieved from storage

GET /authn/log/events

Keyword Arguments

length (int) – The maximum number of results to return. (minimum: 1, default: 10)
start (int) – The starting index in a list of results (starts at one). (minimum: 1, default: 1)
query (str) – A query string to filter users based on matching criteria in fields.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestNotFound – Error response if entity is not found by id (in json format)
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "logEventCollection.json",
    "title": "Log Event Collection Schema",
    "description": "Event List",
    "type": "object",
    "properties": {
        "loggingEvent": {
            "description": "Event log with a list of events",
            "id": "eventData",
            "type": "array",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "id": "logEvent.json",
                "title": "Log Event Schema",
                "description": "A logging event that describes the event code and basic information for logging events",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "The system assigned unique ID of the instance record; UUID"
                    },
                    "eventType": {
                        "$schema": "http://json-schema.org/draft-04/schema#",
                        "id": "logEventType.json",
                        "title": "Log Event Type Schema",
                        "description": "Log event type",
                        "type": "string",
                        "enum": [
                            "PASSWORD_RESET",
                            "PASSWORD_CREATE",
                            "PASSWORD_CHANGE",
                            "SUCCESSFUL_LOGIN_ATTEMPT",
                            "FAILED_LOGIN_ATTEMPT",
                            "USER_BLOCK"
                        ]
                    },
                    "tenant": {
                        "type": "string",
                        "description": "The tenant for which the event occurred"
                    },
                    "userId": {
                        "type": "string",
                        "description": "User ID for which the event is registered."
                    },
                    "ip": {
                        "type": "string",
                        "description": "Client IP address of registered user Okapi"
                    },
                    "browserInformation": {
                        "type": "string",
                        "description": "Client's browser information obtained from User-Agent http header"
                    },
                    "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Event registration time"
                    },
                    "metadata": {
                        "$schema": "http://json-schema.org/draft-04/schema#",
                        "id": "metadata.json",
                        "title": "Metadata Schema",
                        "description": "Record metadata",
                        "type": "object",
                        "properties": {
                            "createdDate": {
                                "description": "Date and time when the record was created",
                                "type": "string"
                            },
                            "createdByUserId": {
                                "description": "ID of the user who created the record (when available)",
                                "type": "string"
                            },
                            "createdByUsername": {
                                "description": "Username of the user who created the record (when available)",
                                "type": "string"
                            },
                            "updatedDate": {
                                "description": "Date and time when the record was last updated",
                                "type": "string"
                            },
                            "updatedByUserId": {
                                "description": "ID of the user who last updated the record (when available)",
                                "type": "string"
                            },
                            "updatedByUsername": {
                                "description": "Username of the user who last updated the record (when available)",
                                "type": "string"
                            }
                        }
                    }
                },
                "required": [
                    "tenant",
                    "userId",
                    "eventType"
                ],
                "additionalProperties": false
            }
        },
        "totalRecords": {
            "description": "Number of entries in the event log",
            "type": "integer"
        }
    },
    "required": [
        "loggingEvent",
        "totalRecords"
    ]
}

getloginattempts(userId)

Get login attempts for a single user

GET /authn/loginAttempts/{userId}

Parameters

userId (str) – User identifier

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestNotFound – Error response if entity is not found by id (in json format)
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "loginAttempts.json",
    "title": "Login Attempts Schema",
    "description": "An object describing a login attempt",
    "type": "object",
    "properties": {
        "id": {
            "description": "Unique id",
            "type": "string"
        },
        "userId": {
            "description": "Unique user id",
            "type": "string"
        },
        "lastAttempt": {
            "description": "Last attempt date",
            "type": "string",
            "format": "date-time"
        },
        "attemptCount": {
            "description": "Number of user login attempts",
            "type": "integer"
        }
    }
}

getpasswordactionbyid(actionId)

Retrieves action record by id

GET /authn/password-reset-action/{actionId}

Parameters

actionId (str) – Action Identifier

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestNotFound – Error response if entity is not found by id (in json format)
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "passwordCreateAction.json",
    "title": "Password Create Action Schema",
    "description": "A password create action response",
    "type": "object",
    "properties": {
        "id": {
            "description": "ID of the password reset action received in the API request",
            "type": "string"
        },
        "userId": {
            "description": "User ID to register password reset action",
            "type": "string"
        },
        "expirationTime": {
            "description": "password expiration time",
            "type": "string",
            "format": "date-time"
        }
    },
    "required": [
        "id",
        "userId",
        "expirationTime"
    ]
}

login(loginCredentials)

Get a new login token

POST /authn/login

Parameters

loginCredentials (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "loginCredentials.json",
    "title": "Login Credentials Schema",
    "description": "An entity that describes the basic credentials for a user to log on to the system",
    "type": "object",
    "properties": {
        "username": {
            "description": "Username in the system, case insensitive",
            "type": "string"
        },
        "userId": {
            "description": "Unique user id",
            "type": "string"
        },
        "password": {
            "description": "User password",
            "type": "string"
        }
    },
    "required": [
        "password"
    ]
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "loginResponse.json",
    "title": "Login Response Schema",
    "description": "Successful login response ",
    "type": "object",
    "properties": {
        "okapiToken": {
            "description": "session token (X-Okapi-Token format)",
            "type": "string"
        },
        "refreshToken": {
            "description": "refresh token",
            "type": "string"
        }
    },
    "required": [
        "okapiToken"
    ]
}

loginwithexpiry(loginCredentials)

Get an expiring refresh and access token

POST /authn/login-with-expiry

Parameters

loginCredentials (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "loginCredentials.json",
    "title": "Login Credentials Schema",
    "description": "An entity that describes the basic credentials for a user to log on to the system",
    "type": "object",
    "properties": {
        "username": {
            "description": "Username in the system, case insensitive",
            "type": "string"
        },
        "userId": {
            "description": "Unique user id",
            "type": "string"
        },
        "password": {
            "description": "User password",
            "type": "string"
        }
    },
    "required": [
        "password"
    ]
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Login Response With Expiry Schema",
    "description": "Object returned on successful login or on token refresh",
    "type": "object",
    "properties": {
        "accessTokenExpiration": {
            "description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
            "type": "string"
        },
        "refreshTokenExpiration": {
            "description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
            "type": "string"
        }
    },
    "required": [
        "accessTokenExpiration",
        "refreshTokenExpiration"
    ]
}

logout()

Logs the user out on their current device

POST /authn/logout

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

logoutall()

Logs the user out on all of their devices

POST /authn/logout-all

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

refreshtoken()

Get a new refresh and access token

POST /authn/refresh

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Login Response With Expiry Schema",
    "description": "Object returned on successful login or on token refresh",
    "type": "object",
    "properties": {
        "accessTokenExpiration": {
            "description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
            "type": "string"
        },
        "refreshTokenExpiration": {
            "description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
            "type": "string"
        }
    },
    "required": [
        "accessTokenExpiration",
        "refreshTokenExpiration"
    ]
}

resetpassword(passwordResetAction)

Resets password for user in record and deletes action record

POST /authn/reset-password

Parameters

passwordResetAction (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "passwordResetAction.json",
    "title": "Password Reset Action Schema",
    "description": "Reset password entity",
    "type": "object",
    "properties": {
        "passwordResetActionId": {
            "description": "Action id for reset password",
            "type": "string"
        },
        "newPassword": {
            "description": "New password for update",
            "type": "string"
        }
    },
    "required": [
        "passwordResetActionId",
        "newPassword"
    ]
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "passwordResetResponse.json",
    "title": "Password Reset Action Response Schema",
    "description": "Response entity to reset the password",
    "type": "object",
    "properties": {
        "isNewPassword": {
            "description": "Indicates the presence of a new password for the user",
            "type": "boolean"
        }
    }
}

savelogevent(logEvent)

Saves received event into the storage

POST /authn/log/events

Parameters

logEvent (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "logEvent.json",
    "title": "Log Event Schema",
    "description": "A logging event that describes the event code and basic information for logging events",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "The system assigned unique ID of the instance record; UUID"
        },
        "eventType": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "logEventType.json",
            "title": "Log Event Type Schema",
            "description": "Log event type",
            "type": "string",
            "enum": [
                "PASSWORD_RESET",
                "PASSWORD_CREATE",
                "PASSWORD_CHANGE",
                "SUCCESSFUL_LOGIN_ATTEMPT",
                "FAILED_LOGIN_ATTEMPT",
                "USER_BLOCK"
            ]
        },
        "tenant": {
            "type": "string",
            "description": "The tenant for which the event occurred"
        },
        "userId": {
            "type": "string",
            "description": "User ID for which the event is registered."
        },
        "ip": {
            "type": "string",
            "description": "Client IP address of registered user Okapi"
        },
        "browserInformation": {
            "type": "string",
            "description": "Client's browser information obtained from User-Agent http header"
        },
        "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Event registration time"
        },
        "metadata": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "metadata.json",
            "title": "Metadata Schema",
            "description": "Record metadata",
            "type": "object",
            "properties": {
                "createdDate": {
                    "description": "Date and time when the record was created",
                    "type": "string"
                },
                "createdByUserId": {
                    "description": "ID of the user who created the record (when available)",
                    "type": "string"
                },
                "createdByUsername": {
                    "description": "Username of the user who created the record (when available)",
                    "type": "string"
                },
                "updatedDate": {
                    "description": "Date and time when the record was last updated",
                    "type": "string"
                },
                "updatedByUserId": {
                    "description": "ID of the user who last updated the record (when available)",
                    "type": "string"
                },
                "updatedByUsername": {
                    "description": "Username of the user who last updated the record (when available)",
                    "type": "string"
                }
            }
        }
    },
    "required": [
        "tenant",
        "userId",
        "eventType"
    ],
    "additionalProperties": false
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "logResponse.json",
    "title": "Log Response Schema",
    "description": "The log event object containing the message received from LoginAPI",
    "type": "object",
    "properties": {
        "message": {
            "description": "The message containing API response information",
            "type": "string"
        }
    },
    "required": [
        "message"
    ]
}

token(**kwargs)

Get a new login token from the authorization code

GET /authn/token

Keyword Arguments

code (str) – temporary authentication code
redirect-uri (str) – initial uri that was used as redirect uri for getting authentication code

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Login Response With Expiry Schema",
    "description": "Object returned on successful login or on token refresh",
    "type": "object",
    "properties": {
        "accessTokenExpiration": {
            "description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
            "type": "string"
        },
        "refreshTokenExpiration": {
            "description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
            "type": "string"
        }
    },
    "required": [
        "accessTokenExpiration",
        "refreshTokenExpiration"
    ]
}

updatecredentials(updateCredentials)

Self-update existing credentials.

POST /authn/update

Parameters

updateCredentials (dict) – See Schema below.

Raises

OkapiRequestError – Error response in JSON format for validation errors.
OkapiRequestUnauthorized – Error response in JSON format if user is not authorized to perform operation.
OkapiRequestUnprocessableEntity – Error response in JSON format for unprocessable entity.
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "updateCredentials.json",
    "title": "Update Credentials Schema",
    "description": "An entity that describes the necessary data to update a user password",
    "type": "object",
    "properties": {
        "username": {
            "description": "username",
            "type": "string"
        },
        "userId": {
            "description": "Unique user id",
            "type": "string"
        },
        "password": {
            "description": "The current password of the user who will be replaced by the new one",
            "type": "string"
        },
        "newPassword": {
            "description": "New user password",
            "type": "string"
        }
    },
    "required": [
        "username",
        "password",
        "newPassword"
    ]
}

validatepasswordrepeatability(password)

Validate password for repeatability

POST /authn/password/repeatable

Parameters: password (dict) – See Schema below.
Returns: See Schema below.
Return type: dict
Raises: OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "password.json",
    "title": "Password Schema",
    "description": "Object with password property",
    "type": "object",
    "properties": {
        "password": {
            "type": "string",
            "description": "Password"
        },
        "userId": {
            "type": "string",
            "description": "User Id"
        }
    },
    "required": [
        "password",
        "userId"
    ]
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "passwordValid.json",
    "title": "Password validation result",
    "description": "Password success validation result",
    "type": "object",
    "properties": {
        "result": {
            "type": "string",
            "description": "Password validation result message"
        }
    },
    "required": [
        "result"
    ]
}