SAML Login version v1
https://github.com/folio-org/mod-login-saml
mod-login-saml API
This module provides an SAML2-based login mechanism to authenticate user in FOLIO through SSO credentials
/saml
Regenerate SAML configuration (keyfile and passwords). The response contains the sp-metadata.xml file
get /saml/regenerate
Regenerate SAML configuration (keyfile and passwords). The response contains the sp-metadata.xml file
HTTP status code 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"
}
}
}HTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorGenerates SAMLRequest and RelayState parameters for initiating a SAML login process
Preflight CORS for /saml/login
post /saml/login
Generates SAMLRequest and RelayState parameters for initiating a SAML login process
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"
}
}
}HTTP status code 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"
}
}
}HTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorRedirect browser to sso-landing page with generated token.
Preflight CORS for /saml/callback
post /saml/callback
Redirect browser to sso-landing page with generated token.
Body
Media type: application/octet-stream
Type: string
Media type: application/x-www-form-urlencoded
Type: string
HTTP status code 302
Generate JWT token and set cookie
Headers
- Set-Cookie: required(string)
- x-okapi-token: required(string)
- Location: required(string)
HTTP status code 400
Bad request
Body
Media type: text/plain
Type: any
Example:
Bad requestHTTP status code 401
Unauthorized
Body
Media type: text/plain
Type: any
Example:
UnauthorizedHTTP status code 403
Forbidden
Body
Media type: text/plain
Type: any
Example:
ForbiddenHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorRedirect browser to sso-landing page with expiring access and refresh tokens.
Preflight CORS for /saml/callback-with-expiry
post /saml/callback-with-expiry
Redirect browser to sso-landing page with expiring access and refresh tokens.
Body
Media type: application/octet-stream
Type: string
Media type: application/x-www-form-urlencoded
Type: string
HTTP status code 302
Generate JWT token and set cookie
Headers
- Location: required(string)
HTTP status code 400
Bad request
Body
Media type: text/plain
Type: any
Example:
Bad requestHTTP status code 401
Unauthorized
Body
Media type: text/plain
Type: any
Example:
UnauthorizedHTTP status code 403
Forbidden
Body
Media type: text/plain
Type: any
Example:
ForbiddenHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorDecides if SSO login is configured properly, returns true or false
get /saml/check
Decides if SSO login is configured properly, returns true or false
HTTP status code 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"
}
}
}HTTP status code 404
Module is not deployed
Body
Media type: text/html
Type: any
Example:
Module is not deployedHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorSave SAML module configuration
get /saml/configuration
HTTP status code 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
}
}
}HTTP status code 500
Body
Media type: text/plain
Type: any
Example:
Internal server errorput /saml/configuration
Save SAML module 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
}
}
}HTTP status code 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
}
}
}HTTP status code 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"
}
}
}HTTP status code 500
Body
Media type: text/plain
Type: any
Example:
Internal server errorget /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
HTTP status code 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"
}
}
}HTTP status code 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"
}
}
}HTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server error