saml-login.raml

#%RAML 1.0
title: SAML Login
version: v1
baseUri: https://github.com/folio-org/mod-login-saml

documentation:
  - title: mod-login-saml API
    content: This module provides an SAML2-based login mechanism to authenticate user in FOLIO through SSO credentials

types:
  SamlCheck: !include schemas/SamlCheck.json
  SamlLogin: !include schemas/SamlLogin.json
  SamlLoginRequest: !include schemas/SamlLoginRequest.json
  SamlConfigRequest: !include schemas/SamlConfigRequest.json
  SamlConfig: !include schemas/SamlConfig.json
  SamlRegenerateResponse: !include schemas/SamlRegenerateResponse.json
  SamlValidateResponse: !include schemas/SamlValidateResponse.json

/saml:
  /regenerate:
    get:
      description: Regenerate SAML configuration (keyfile and passwords). The response contains the sp-metadata.xml file
      responses:
        200:
          body:
            application/json:
              type: SamlRegenerateResponse
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /login:
    post:
      body:
        application/json:
          type: SamlLoginRequest
      description: Generates SAMLRequest and RelayState parameters for initiating a SAML login process
      responses:
        200:
          description: "Return with HTML page in case POST_BINDING is used"
          body:
            application/json:
              type: SamlLogin
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    options:
      description: "Preflight CORS for /saml/login"
      responses:
        204:
          description: "Return with appropriate CORS headers"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
  /callback:
    post:
      description: Redirect browser to sso-landing page with generated token.
      body:
        application/octet-stream:
          type: string
        application/x-www-form-urlencoded:
          type: string
      responses:
        302:
          description: "Generate JWT token and set cookie"
          headers:
            Set-Cookie:
            x-okapi-token:
            Location:
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        401:
          description: "Unauthorized"
          body:
            text/plain:
              example: "Unauthorized"
        403:
          description: "Forbidden"
          body:
            text/plain:
              example: "Forbidden"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    options:
      description: "Preflight CORS for /saml/callback"
      responses:
        204:
          description: "Return with appropriate CORS headers"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
  /check:
    get:
      description: Decides if SSO login is configured properly, returns true or false
      responses:
        200:
          body:
            application/json:
              type: SamlCheck
        404:
          description: Module is not deployed
          body:
            text/html:
              example: "Module is not deployed"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /configuration:
    get:
      responses:
        200:
          body:
            application/json:
              type: SamlConfig
        500:
          body:
            text/plain:
              example: "Internal server error"
    put:
      description: Save SAML module configuration
      body:
        application/json:
          type: SamlConfigRequest
      responses:
        200:
          body:
            application/json:
              type: SamlConfig
        400:
          body:
            application/json:
              type: SamlValidateResponse
        500:
          body:
            text/plain:
              example: "Internal server error"
  /validate:
    get:
      queryParameters:
        type:
          displayName: Type
          type: string
          enum: [idpurl,okapiurl]
          description: The type of configuration directive
          example: idpurl
          required: true
        value:
          displayName: Value
          type: string
          description: The value of configuration directive
          example: http://localhost
          required: true
      responses:
        200:
          body:
            application/json:
              type: SamlValidateResponse
        400:
          body:
            application/json:
              type: SamlValidateResponse
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"