SAML Login (v1)

https://github.com/folio-org/mod-login-saml

Table of contents

mod-login-saml API

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

/saml

GET /saml/regenerate

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

GET /saml/regenerate

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /saml/login

Generates SAMLRequest and RelayState parameters for initiating a SAML login process

POST /saml/login
Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 200

Return with HTML page in case POST_BINDING is used

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

OPTIONS /saml/login

Preflight CORS for /saml/login

OPTIONS /saml/login

Response 204

Return with appropriate CORS headers

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

POST /saml/callback

Redirect browser to sso-landing page with generated token.

POST /saml/callback
Body

Media type: application/octet-stream

Type: string

Media type: application/x-www-form-urlencoded

Type: string

Response 302

Generate JWT token and set cookie

Headers
  • Set-Cookie: required (string)
  • x-okapi-token: required (string)
  • Location: required (string)

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 401

Unauthorized

Body

Media type: text/plain

Type: any

Example:

Unauthorized

Response 403

Forbidden

Body

Media type: text/plain

Type: any

Example:

Forbidden

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

OPTIONS /saml/callback

Preflight CORS for /saml/callback

OPTIONS /saml/callback

Response 204

Return with appropriate CORS headers

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

POST /saml/callback-with-expiry

Redirect browser to sso-landing page with expiring access and refresh tokens.

POST /saml/callback-with-expiry
Body

Media type: application/octet-stream

Type: string

Media type: application/x-www-form-urlencoded

Type: string

Response 302

Generate JWT token and set cookie

Headers
  • Location: required (string)

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 401

Unauthorized

Body

Media type: text/plain

Type: any

Example:

Unauthorized

Response 403

Forbidden

Body

Media type: text/plain

Type: any

Example:

Forbidden

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

OPTIONS /saml/callback-with-expiry

Preflight CORS for /saml/callback-with-expiry

OPTIONS /saml/callback-with-expiry

Response 204

Return with appropriate CORS headers

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

GET /saml/check

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

GET /saml/check

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 404

Module is not deployed

Body

Media type: text/html

Type: any

Example:

Module is not deployed

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /saml/configuration

GET /saml/configuration

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$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
    },
    "callback": {
      "description": "Where the IDP should call back after login is successful. Either callback or callback-with-expiry. Defaults to callback-with-expiry if not present.",
      "type": "string",
      "required": false
    },
    "useSecureTokens": {
      "type": "boolean",
      "description": "When present, and true, and when callback is configured with the value 'callback', enables the refresh token payload on the /callback endpoint.",
      "required": false
    }
  }
}

Response 500

Body

Media type: text/plain

Type: any

Example:

Internal server error

PUT /saml/configuration

Save SAML module configuration

PUT /saml/configuration
Body

Media type: application/json

Type: json

Content:

{
  "$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
    },
    "callback": {
      "description": "Where the IDP should call back after login is successful. Either callback or callback-with-expiry. Defaults to callback-with-expiry if not present.",
      "type": "string",
      "required": false
    },
    "useSecureTokens": {
      "type": "boolean",
      "description": "When present, and 'true', and when callback is configured with the value 'callback', enables the refresh token payload on the /callback endpoint.",
      "required": false
    }
  }
}

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$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
    },
    "callback": {
      "description": "Where the IDP should call back after login is successful. Either callback or callback-with-expiry. Defaults to callback-with-expiry if not present.",
      "type": "string",
      "required": false
    },
    "useSecureTokens": {
      "type": "boolean",
      "description": "When present, and true, and when callback is configured with the value 'callback', enables the refresh token payload on the /callback endpoint.",
      "required": false
    }
  }
}

Response 400

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 500

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /saml/validate

GET /saml/validate
Query Parameters
  • type: required (one of idpurl, okapiurl)

    The type of configuration directive

    Example:

    idpurl
  • value: required (string)

    The value of configuration directive

    Example:

    http://localhost

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 400

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error