foliolib.folio.api.login.Login

class foliolib.folio.api.login.Login(tenant: str, okapi: Optional[foliolib.okapi.okapiClient.OkapiClient] = None)

Bases: foliolib.folio.FolioApi

mod-login API

This module provides a username/password based login mechanism for FOLIO credentials

Parameters

tenant (str) – Tenant id
okapi (OkapiClient, optional) – Instance of OkapiClient. Defaults to None.

Methods

`delete_credentials`(**kwargs)	Remove a user's login credentials from the system
`delete_event`(eventsId)	Removes events by filter
`get_credentialsExistences`(**kwargs)	Returns single property 'credentialsExist' with true, if user has local password
`get_events`(**kwargs)	Returns a list of events retrieved from storage
`get_loginAttempt`(loginAttemptsId)	Get login attempts for a single user
`get_passwordResetAction`(actionId)	Retrieves action record by id
`set_credential`(credential)	Add a new login to the system.
`set_event`(event)	Saves received event into the storage
`set_login`(login)	Get a new login token
`set_passwordResetAction`(passwordResetAction)	Saves action to storage
`set_repeatable`(repeatable)	Validate password for repeatability
`set_resetPassword`(resetPassword)	Resets password for user in record and deletes action record
`set_update`(update)	Self-update existing credentials.

delete_credentials(**kwargs)

Remove a user’s login credentials from the system

DELETE /authn/credentials

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

userId (str (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$) – ): User Id

Raises

OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

delete_event(eventsId: str)

Removes events by filter

DELETE /authn/log/events/{eventsId}

Parameters

eventsId (str) –

Returns

See Schema below

Return type

dict

Raises

OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/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"
  ]
}

get_credentialsExistences(**kwargs)

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

GET /authn/credentials-existence

Parameters: **kwargs (properties) – Keyword Arguments
Keyword Arguments: userId (str (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$) – ): User id
Returns: See Schema below
Return type: dict
Raises: OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Credentials existence",
  "type": "object",
  "properties": {
    "credentialsExist": {
      "type": "boolean",
      "description": "True if user has local password"
    }
  },
  "additionalProperties": false,
  "required": [
    "credentialsExist"
  ]
}

get_events(**kwargs)

Returns a list of events retrieved from storage

GET /authn/log/events

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

length (int) –
(default=10) The maximum number of results to return.

Example
- 10
start (int) – (default=1) The starting index in a list of results (starts at one).
query (str) – A query string to filter users based on matching criteria in fields.

Returns

See Schema below

Return type

dict

Raises

OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Event List",
  "type": "object",
  "properties": {
    "loggingEvent": {
      "description": "Event log with a list of events",
      "id": "eventData",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "logEvent.json"
      }
    },
    "totalRecords": {
      "description": "Number of entries in the event log",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "loggingEvent",
    "totalRecords"
  ]
}

get_loginAttempt(loginAttemptsId: str)

Get login attempts for a single user

GET /authn/loginAttempts/{loginAttemptsId}

Parameters

loginAttemptsId (str) –

Returns

See Schema below

Return type

dict

Raises

OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Login Attempts Schema",
  "type": "object",
  "description": "An object describing a login attempt",
  "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"
    }
  }
}

get_passwordResetAction(actionId: str)

Retrieves action record by id

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

Parameters

actionId (str) –

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Reset password entity",
  "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"
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "userId",
    "expirationTime"
  ]
}

set_credential(credential: dict)

Add a new login to the system. N.B. A non-empty password must be provided.

POST /authn/credentials

Parameters

credential (dict) – See Schema below

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "title": "Login Credentials Schema",
  "type": "object",
  "description": "An entity that describes the basic credentials for a user to log on to the system",
  "properties": {
    "username": {
      "description": "Username in the system, case insensitive",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "User password",
      "type": "string"
    },
    "tenant": {
      "description": "Tenant; parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

set_event(event: dict)

Saves received event into the storage

POST /authn/log/events

Parameters: event (dict) – See Schema below
Returns: See Schema below
Return type: dict
Raises: OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A logging event that describes the event code and basic information for logging events",
  "additionalProperties": true,
  "properties": {
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "eventType": {
      "enum": [
        "PASSWORD_RESET",
        "PASSWORD_CREATE",
        "PASSWORD_CHANGE",
        "SUCCESSFUL_LOGIN_ATTEMPT",
        "FAILED_LOGIN_ATTEMPT",
        "USER_BLOCK"
      ],
      "description": "Event type"
    },
    "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": {
      "type": "object",
      "description": "Metadata about creation and changes to logging event, provided by the server (client should not provide)",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "tenant",
    "userId",
    "eventType"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/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"
  ]
}

set_login(login: dict)

Get a new login token

POST /authn/login

Parameters

login (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestUnprocessableEntity – Unprocessable Entity
OkapiFatalError – Server Error

Headers

x-okapi-token - refreshtoken

Schema

{
  "title": "Login Credentials Schema",
  "type": "object",
  "description": "An entity that describes the basic credentials for a user to log on to the system",
  "properties": {
    "username": {
      "description": "Username in the system, case insensitive",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "User password",
      "type": "string"
    },
    "tenant": {
      "description": "Tenant; parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Object returned on successful login",
  "type": "object",
  "properties": {
    "okapiToken": {
      "description": "session token (X-Okapi-Token format)",
      "type": "string"
    },
    "refreshToken": {
      "description": "refresh token",
      "type": "string"
    }
  },
  "required": [
    "okapiToken"
  ]
}

set_passwordResetAction(passwordResetAction: dict)

Saves action to storage

POST /authn/password-reset-action

Parameters

passwordResetAction (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Reset password entity",
  "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"
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "userId",
    "expirationTime"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/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"
    }
  },
  "additionalProperties": false
}

set_repeatable(repeatable: dict)

Validate password for repeatability

POST /authn/password/repeatable

Parameters: repeatable (dict) – See Schema below
Returns: See Schema below
Return type: dict
Raises: OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/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#",
  "description": "result",
  "type": "object",
  "properties": {
    "result": {
      "type": "string",
      "description": "result"
    }
  },
  "required": [
    "result"
  ]
}

set_resetPassword(resetPassword: dict)

Resets password for user in record and deletes action record

POST /authn/reset-password

Parameters

resetPassword (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/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"
    }
  },
  "additionalProperties": false,
  "required": [
    "passwordResetActionId",
    "newPassword"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/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"
    }
  },
  "additionalProperties": false
}

set_update(update: dict)

Self-update existing credentials. N.B. A non-empty password must be provided.

POST /authn/update

Parameters

update (dict) – See Schema below

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiRequestUnprocessableEntity – Unprocessable Entity
OkapiFatalError – Server Error

Schema

{
  "title": "Update Credentials Schema",
  "type": "object",
  "description": "An entity that describes the necessary data to update a user password",
  "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"
    }
  }
}