foliolib.folio.api.loginSaml.SamlLogin

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

Bases: foliolib.folio.FolioApi

mod-login-saml API

This module provides an SAML2-based login mechanism to authenticate user in FOLIO through SSO credentials

Parameters

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

Methods

`get_checks`()	Decides if SSO login is configured properly, returns true or false
`get_configurations`()	`GET /saml/configuration`
`get_regenerates`()	Regenerate SAML configuration (keyfile and passwords).
`get_validates`(**kwargs)	`GET /saml/validate`
`modify_configuration`(configuration)	Save SAML module configuration
`set_callback`(callback)	Redirect browser to sso-landing page with generated token.
`set_login`(login)	Generates SAMLRequest and RelayState parameters for initiating a SAML login process

get_checks()

Decides if SSO login is configured properly, returns true or false

GET /saml/check

Returns

See Schema below

Return type

dict

Raises

OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "Indicates whether SAML is configured and active",
  "properties": {
    "active": {
      "description": "Indicates whether SAML is configured and active",
      "required": true,
      "type": "boolean"
    }
  }
}

get_configurations()

GET /saml/configuration

Returns: See Schema below
Return type: dict
Raises: OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "Holds SAML configuration properties",
  "properties": {
    "idpUrl": {
      "description": "the URL of the identity provider",
      "type": "string",
      "format": "uri",
      "required": true
    },
    "samlBinding": {
      "description": "the SAML binding to use",
      "type": "string",
      "enum": [
        "POST",
        "REDIRECT"
      ],
      "required": false
    },
    "samlAttribute": {
      "description": "the SAML attribute to use for matching against a FOLIO user",
      "type": "string",
      "required": false
    },
    "userProperty": {
      "description": "the property from the user record to use for matching against the SAML attribute",
      "type": "string",
      "required": false
    },
    "metadataInvalidated": {
      "type": "boolean",
      "description": "Indicates that there is a change in configuration that can break working of module, like IdP URL or encrityon key changed.",
      "required": false
    },
    "okapiUrl": {
      "description": "Where to find OKAPI",
      "type": "string",
      "format": "uri",
      "required": true
    }
  }
}

get_regenerates()

Regenerate SAML configuration (keyfile and passwords). The response contains the sp-metadata.xml file

GET /saml/regenerate

Returns: See Schema below
Return type: dict
Raises: OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "Wraps SP (service provider) metadata XML content (base64 encoded) in JSON.",
  "properties": {
    "fileContent": {
      "description": "SP (service provider) metadata",
      "required": true,
      "type": "string"
    }
  }
}

get_validates(**kwargs)

GET /saml/validate

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

type (str) –
The type of configuration directive

Example
- idpurl
value (str) –
The value of configuration directive

Example
- http://localhost

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "Indicates whether or not the SAML configuration is valid",
  "properties": {
    "valid": {
      "description": "Indicates whether or not the SAML configuration is valid",
      "required": true,
      "type": "boolean"
    },
    "error": {
      "description": "Describes errors with the SAML configuration",
      "required": false,
      "type": "string"
    }
  }
}

modify_configuration(configuration: dict)

Save SAML module configuration

PUT /saml/configuration

Parameters

configuration (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-03/schema#",
  "type": "object",
  "description": "Holds SAML configuration properties",
  "properties": {
    "idpUrl": {
      "description": "the URL of the identity provider",
      "type": "string",
      "format": "uri",
      "required": true
    },
    "samlBinding": {
      "description": "the SAML binding to use",
      "type": "string",
      "enum": [
        "POST",
        "REDIRECT"
      ],
      "required": true
    },
    "samlAttribute": {
      "description": "the SAML attribute to use for matching against a FOLIO user",
      "type": "string",
      "required": true
    },
    "idpMetadata": {
      "description": "the Identity Provider Metadata",
      "type": "string",
      "required": false
    },
    "userProperty": {
      "description": "the property from the user record to use for matching against the SAML attribute",
      "type": "string",
      "required": true
    },
    "okapiUrl": {
      "description": "Where to find OKAPI",
      "type": "string",
      "format": "uri",
      "required": true
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "Holds SAML configuration properties",
  "properties": {
    "idpUrl": {
      "description": "the URL of the identity provider",
      "type": "string",
      "format": "uri",
      "required": true
    },
    "samlBinding": {
      "description": "the SAML binding to use",
      "type": "string",
      "enum": [
        "POST",
        "REDIRECT"
      ],
      "required": false
    },
    "samlAttribute": {
      "description": "the SAML attribute to use for matching against a FOLIO user",
      "type": "string",
      "required": false
    },
    "userProperty": {
      "description": "the property from the user record to use for matching against the SAML attribute",
      "type": "string",
      "required": false
    },
    "metadataInvalidated": {
      "type": "boolean",
      "description": "Indicates that there is a change in configuration that can break working of module, like IdP URL or encrityon key changed.",
      "required": false
    },
    "okapiUrl": {
      "description": "Where to find OKAPI",
      "type": "string",
      "format": "uri",
      "required": true
    }
  }
}

set_callback(callback: str)

Redirect browser to sso-landing page with generated token.

POST /saml/callback

Parameters

callback (str) – See Schema below

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiRequestForbidden – Forbidden
OkapiFatalError – Server Error

Schema

string

set_login(login: dict)

Generates SAMLRequest and RelayState parameters for initiating a SAML login process

POST /saml/login

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

Schema

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "the payload sent to the POST /saml/login endpoint",
  "properties": {
    "stripesUrl": {
      "description": "the URL that the user will be redirected to upon successful login",
      "required": true,
      "type": "string"
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "type": "object",
  "description": "Payload response from the POST /saml/login endpoint",
  "properties": {
    "bindingMethod": {
      "description": "the HTTP method binding to use",
      "required": true,
      "type": "string",
      "enum": [
        "POST",
        "GET"
      ]
    },
    "location": {
      "description": "the URL to redirect to when using the GET/redirect binding",
      "required": true,
      "type": "string"
    },
    "samlRequest": {
      "description": "the generated SAML request to be submitted when using the POST binding",
      "required": false,
      "type": "string"
    },
    "relayState": {
      "description": "data that the IdP will echo back unchanged along with the SAML response",
      "required": false,
      "type": "string"
    }
  }
}