foliolib.folio.api.usersKeycloak.Userskeycloak

class foliolib.folio.api.usersKeycloak.Userskeycloak(tenant: str)

Bases: foliolib.folio.FolioApi

Users Keycloak API

Base class of the Folio API

Parameters: tenant (str) – Tenant id

Methods

`createuser`(user, **kwargs)	Create a new user
`deletemigration`(id_)	Delete a user migration
`deleteuser`(id_)	Delete user with given id
`deleteusers`(**kwargs)	Delete a collection of users selected by a CQL query; \| this doesn't delete proxyFor records that reference them
`generatepasswordresetlink`(generateLinkRequest)	Generate and send password reset link
`getmigration`(id_)	Retrieve a user migration
`getmigrations`(**kwargs)	Retrieve a list of user migrations
`getuser`(id_)	Get a single user
`getuserbyselfreference`(**kwargs)	Get a user by self reference
`getusers`(**kwargs)	Retrieve a list of users
`migrateusers`()	Migrate users from mod-users to Keycloak
`passwordreset`(passwordReset)	`POST /users-keycloak/password-reset/reset`
`recoverforgottenusername`(identifier)	called when a user has forgotten a username
`resetforgottenpassword`(identifier)	called when a user has forgotten a password
`updateuser`(user, id_)	Update user with given id
`validatepasswordresetlink`()	Validates password reset link

createuser(user, **kwargs)

Create a new user

POST /users-keycloak/users

Parameters

user (dict) – See Schema below.

Keyword Arguments

keycloakOnly (bool) – Create auth user only during user creation (default: False)

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestUnprocessableEntity – Validation errors
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "User Schema",
    "description": "A user",
    "type": "object",
    "properties": {
        "username": {
            "description": "A unique name belonging to a user. Typically used for login",
            "type": "string"
        },
        "id": {
            "description": "A globally unique (UUID) identifier for the user",
            "type": "string",
            "format": "uuid"
        },
        "externalSystemId": {
            "description": "A unique ID that corresponds to an external authority",
            "type": "string"
        },
        "barcode": {
            "description": "The unique library barcode for this user",
            "type": "string"
        },
        "active": {
            "description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
            "type": "boolean"
        },
        "type": {
            "description": "The class of user like staff or patron; this is different from patronGroup",
            "type": "string"
        },
        "patronGroup": {
            "description": "A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group",
            "type": "string",
            "format": "uuid"
        },
        "departments": {
            "description": "A list of UUIDs corresponding to the departments the user belongs to, see /departments API",
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "format": "uuid"
            }
        },
        "meta": {
            "description": "Deprecated",
            "type": "object"
        },
        "proxyFor": {
            "description": "Deprecated",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "personal": {
            "description": "Personal information about the user",
            "$ref": "personal.json"
        },
        "enrollmentDate": {
            "description": "The date in which the user joined the organization",
            "type": "string",
            "format": "date-time"
        },
        "expirationDate": {
            "description": "The date for when the user becomes inactive",
            "type": "string",
            "format": "date-time"
        },
        "createdDate": {
            "description": "Deprecated",
            "type": "string",
            "format": "date-time"
        },
        "updatedDate": {
            "description": "Deprecated",
            "type": "string",
            "format": "date-time"
        },
        "metadata": {
            "$ref": "common/metadata.json"
        },
        "tags": {
            "$ref": "common/tags.json"
        },
        "customFields": {
            "description": "Object that contains custom field",
            "type": "object",
            "additionalProperties": true
        }
    },
    "additionalProperties": false
}

deletemigration(id_)

Delete a user migration

DELETE /users-keycloak/migrations/{id}

deleteuser(id_)

Delete user with given id

DELETE /users-keycloak/users/{id}

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
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.

deleteusers(**kwargs)

Delete a collection of users selected by a CQL query; | this doesn’t delete proxyFor records that reference them

DELETE /users-keycloak/users

Keyword Arguments

query (str) – A CQL query string with search conditions.

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

generatepasswordresetlink(generateLinkRequest)

Generate and send password reset link

POST /users-keycloak/password-reset/link

Parameters: generateLinkRequest (dict) – See Schema below.
Returns: See Schema below.
Return type: dict

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "description": "Request to generate and send reset password link",
    "properties": {
        "userId": {
            "type": "string",
            "format": "uuid",
            "description": "Id of user to whom a reset password link is sent"
        }
    },
    "required": [
        "userId"
    ]
}

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "description": "Response for reset password link generation",
    "properties": {
        "link": {
            "type": "string",
            "description": "Link for resetting password"
        }
    },
    "additionalProperties": false
}

getmigration(id_)

Retrieve a user migration

GET /users-keycloak/migrations/{id}

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "userMigrationJob.json",
    "title": "User Migration Job Schema",
    "description": "A user migration job entity for tracking migration's progress",
    "type": "object",
    "properties": {
        "id": {
            "description": "An migration job identifier",
            "type": "string",
            "format": "uuid"
        },
        "status": {
            "description": "An user migration job status",
            "$ref": "types/userMigrationJobStatus.json"
        },
        "totalRecords": {
            "type": "integer"
        },
        "startedAt": {
            "description": "A user migration job start timestamp",
            "type": "string",
            "format": "date-time"
        },
        "finishedAt": {
            "description": "A user migration job end timestamp",
            "type": "string",
            "format": "date-time"
        }
    }
}

getmigrations(**kwargs)

Retrieve a list of user migrations

GET /users-keycloak/migrations

Keyword Arguments

query (str) – A CQL query string with search conditions.
offset (int) – Skip over a number of elements by specifying an offset value for the query. (minimum: 0, default: 0)
limit (int) – Limit the number of elements returned in the response. (minimum: 0, maximum: 500, default: 10)

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "userMigrationJobs.json",
    "title": "List of User Migration Jobs Schema",
    "description": "A list of user migration job entities",
    "type": "object",
    "properties": {
        "migrations": {
            "description": "List of Migration Jobs",
            "type": "array",
            "id": "migrations",
            "items": {
                "$ref": "userMigrationJob.json"
            }
        },
        "totalRecords": {
            "type": "integer"
        }
    }
}

getuser(id_)

Get a single user

GET /users-keycloak/users/{id}

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#",
    "title": "User Schema",
    "description": "A user",
    "type": "object",
    "properties": {
        "username": {
            "description": "A unique name belonging to a user. Typically used for login",
            "type": "string"
        },
        "id": {
            "description": "A globally unique (UUID) identifier for the user",
            "type": "string",
            "format": "uuid"
        },
        "externalSystemId": {
            "description": "A unique ID that corresponds to an external authority",
            "type": "string"
        },
        "barcode": {
            "description": "The unique library barcode for this user",
            "type": "string"
        },
        "active": {
            "description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
            "type": "boolean"
        },
        "type": {
            "description": "The class of user like staff or patron; this is different from patronGroup",
            "type": "string"
        },
        "patronGroup": {
            "description": "A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group",
            "type": "string",
            "format": "uuid"
        },
        "departments": {
            "description": "A list of UUIDs corresponding to the departments the user belongs to, see /departments API",
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "format": "uuid"
            }
        },
        "meta": {
            "description": "Deprecated",
            "type": "object"
        },
        "proxyFor": {
            "description": "Deprecated",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "personal": {
            "description": "Personal information about the user",
            "$ref": "personal.json"
        },
        "enrollmentDate": {
            "description": "The date in which the user joined the organization",
            "type": "string",
            "format": "date-time"
        },
        "expirationDate": {
            "description": "The date for when the user becomes inactive",
            "type": "string",
            "format": "date-time"
        },
        "createdDate": {
            "description": "Deprecated",
            "type": "string",
            "format": "date-time"
        },
        "updatedDate": {
            "description": "Deprecated",
            "type": "string",
            "format": "date-time"
        },
        "metadata": {
            "$ref": "common/metadata.json"
        },
        "tags": {
            "$ref": "common/tags.json"
        },
        "customFields": {
            "description": "Object that contains custom field",
            "type": "object",
            "additionalProperties": true
        }
    },
    "additionalProperties": false
}

getuserbyselfreference(**kwargs)

Get a user by self reference

GET /users-keycloak/_self

Keyword Arguments

include (list) – Indicates which referenced fields should be populated (de-referenced) by the service (items: ($ref: #/components/schemas/includedField))
expandPermissions (bool) – Whether or not to expand permissions listings (default: False)

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestForbidden – Access denied
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#",
    "type": "object",
    "description": "Composite user object",
    "properties": {
        "user": {
            "description": "User object",
            "$ref": "user.json"
        },
        "patronGroup": {
            "description": "Patron group object",
            "$ref": "userGroup.json"
        },
        "permissions": {
            "description": "Permissions object",
            "$ref": "permissionUser.json"
        },
        "proxiesFor": {
            "type": "array",
            "description": "Proxies for, array",
            "id": "proxyFor",
            "items": {
                "$ref": "proxyFor.json"
            }
        },
        "servicePointsUser": {
            "description": "Service point user",
            "$ref": "servicePointUser.json"
        }
    }
}

getusers(**kwargs)

Retrieve a list of users

GET /users-keycloak/users

Keyword Arguments

query (str) – A CQL query string with search conditions.
offset (int) – Skip over a number of elements by specifying an offset value for the query. (minimum: 0, default: 0)
limit (int) – Limit the number of elements returned in the response. (minimum: 0, maximum: 500, default: 10)

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "description": "Collection of users",
    "properties": {
        "users": {
            "description": "List of userdata items",
            "type": "array",
            "id": "usersData",
            "items": {
                "$ref": "user.json"
            }
        },
        "totalRecords": {
            "type": "integer"
        },
        "resultInfo": {
            "$ref": "common/resultInfo.json",
            "readonly": true
        }
    },
    "required": [
        "users",
        "totalRecords"
    ]
}

migrateusers()

Migrate users from mod-users to Keycloak

POST /users-keycloak/migrations

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestUnprocessableEntity – Validation errors
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "userMigrationJob.json",
    "title": "User Migration Job Schema",
    "description": "A user migration job entity for tracking migration's progress",
    "type": "object",
    "properties": {
        "id": {
            "description": "An migration job identifier",
            "type": "string",
            "format": "uuid"
        },
        "status": {
            "description": "An user migration job status",
            "$ref": "types/userMigrationJobStatus.json"
        },
        "totalRecords": {
            "type": "integer"
        },
        "startedAt": {
            "description": "A user migration job start timestamp",
            "type": "string",
            "format": "date-time"
        },
        "finishedAt": {
            "description": "A user migration job end timestamp",
            "type": "string",
            "format": "date-time"
        }
    }
}

passwordreset(passwordReset)

POST /users-keycloak/password-reset/reset

Parameters

passwordReset (dict) – See Schema below.

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestUnprocessableEntity – Validation errors
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Password reset entity",
    "type": "object",
    "properties": {
        "newPassword": {
            "description": "New password",
            "type": "string"
        }
    },
    "additionalProperties": false,
    "required": [
        "newPassword"
    ]
}

recoverforgottenusername(identifier)

called when a user has forgotten a username

POST /users-keycloak/forgotten/username

Parameters

identifier (dict) – See Schema below.

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestUnprocessableEntity – Validation errors
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "description": "Identifier",
    "properties": {
        "id": {
            "type": "string",
            "description": "Id"
        }
    }
}

resetforgottenpassword(identifier)

called when a user has forgotten a password

POST /users-keycloak/forgotten/password

Parameters

identifier (dict) – See Schema below.

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
OkapiRequestUnprocessableEntity – Validation errors
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "description": "Identifier",
    "properties": {
        "id": {
            "type": "string",
            "description": "Id"
        }
    }
}

updateuser(user, id_)

Update user with given id

PUT /users-keycloak/users/{id}

Parameters

user (dict) – See Schema below.

Raises

OkapiRequestError – Bad request, e.g. malformed request body or query parameter
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#",
    "title": "User Schema",
    "description": "A user",
    "type": "object",
    "properties": {
        "username": {
            "description": "A unique name belonging to a user. Typically used for login",
            "type": "string"
        },
        "id": {
            "description": "A globally unique (UUID) identifier for the user",
            "type": "string",
            "format": "uuid"
        },
        "externalSystemId": {
            "description": "A unique ID that corresponds to an external authority",
            "type": "string"
        },
        "barcode": {
            "description": "The unique library barcode for this user",
            "type": "string"
        },
        "active": {
            "description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
            "type": "boolean"
        },
        "type": {
            "description": "The class of user like staff or patron; this is different from patronGroup",
            "type": "string"
        },
        "patronGroup": {
            "description": "A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group",
            "type": "string",
            "format": "uuid"
        },
        "departments": {
            "description": "A list of UUIDs corresponding to the departments the user belongs to, see /departments API",
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "format": "uuid"
            }
        },
        "meta": {
            "description": "Deprecated",
            "type": "object"
        },
        "proxyFor": {
            "description": "Deprecated",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "personal": {
            "description": "Personal information about the user",
            "$ref": "personal.json"
        },
        "enrollmentDate": {
            "description": "The date in which the user joined the organization",
            "type": "string",
            "format": "date-time"
        },
        "expirationDate": {
            "description": "The date for when the user becomes inactive",
            "type": "string",
            "format": "date-time"
        },
        "createdDate": {
            "description": "Deprecated",
            "type": "string",
            "format": "date-time"
        },
        "updatedDate": {
            "description": "Deprecated",
            "type": "string",
            "format": "date-time"
        },
        "metadata": {
            "$ref": "common/metadata.json"
        },
        "tags": {
            "$ref": "common/tags.json"
        },
        "customFields": {
            "description": "Object that contains custom field",
            "type": "object",
            "additionalProperties": true
        }
    },
    "additionalProperties": false
}

validatepasswordresetlink()

Validates password reset link

POST /users-keycloak/password-reset/validate

Raises

OkapiRequestUnprocessableEntity – Validation errors
OkapiRequestFatalError – Error response for unhandled or critical server exceptions, e.g. NullPointerException.