open_xchange_client

# NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
# https://openapi-generator.tech
# Do not edit the class manually.

defmodule OpenXchangeClient.Api.SAML do
  @moduledoc """
  API calls for all endpoints tagged `SAML`.
  """

  alias OpenXchangeClient.Connection
  import OpenXchangeClient.RequestBuilder

  @doc """
  Assertion Consumer Service
  SAML 2.0 Assertion Consumer Service. Accepts `<Response>` messages of the Web Browser SSO Profile per `HTTP-POST` binding.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - tenant (String.t): In a multi-tenant environment, where different tenants might connect to different identity providers, this parameter denotes the tenant to start a SAML flow for. In single-tenant environments this parameter is superfluous.
  - u_nknownbasetype (UNKNOWN_BASE_TYPE):
  - opts (KeywordList): [optional] Optional parameters
  ## Returns

  {:ok, nil} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec acs(
          Tesla.Env.client(),
          String.t(),
          OpenXchangeClient.Model.UNKNOWN_BASE_TYPE.t(),
          keyword()
        ) :: {:ok, nil} | {:error, Tesla.Env.t()}
  def acs(connection, tenant, u_nknownbasetype, _opts \\ []) do
    %{}
    |> method(:post)
    |> url("/saml/#{tenant}/acs")
    |> add_param(:body, :body, u_nknownbasetype)
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {302, false},
      {:default, false}
    ])
  end

  @doc """
  Initiate SAML 2.0 HTTP binding flows
  Initiates any supported SAML 2.0 login and logout flow as described in https://documentation.open-xchange.com/latest/middleware/login/02_saml.html.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - tenant (String.t): In a multi-tenant environment, where different tenants might connect to different identity providers, this parameter denotes the tenant to start a SAML flow for. In single-tenant environments this parameter is superfluous.
  - opts (KeywordList): [optional] Optional parameters
    - :flow (String.t): One of `login`, `relogin` or `logout` to start the respective flow.
    - :session (String.t): Required for flow `logout`. A session ID to determine the correct session.
    - :redirect (String.t): Responds with `302 Found` and sets the response header `Location` to the actual redirect URI.
  ## Returns

  {:ok, OpenXchangeClient.Model.InlineResponse2003.t} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec init(Tesla.Env.client(), String.t(), keyword()) ::
          {:ok, nil}
          | {:ok, OpenXchangeClient.Model.InlineResponse2003.t()}
          | {:error, Tesla.Env.t()}
  def init(connection, tenant, opts \\ []) do
    optional_params = %{
      :flow => :query,
      :session => :query,
      :redirect => :query
    }

    %{}
    |> method(:get)
    |> url("/saml/#{tenant}/init")
    |> add_optional_params(optional_params, opts)
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {200, %OpenXchangeClient.Model.InlineResponse2003{}},
      {302, false},
      {400, false},
      {500, false}
    ])
  end

  @doc """
  Metadata Service
  SAML 2.0 Metadata Service. Provides an `<EntityDescriptor>` XML document describing the built-in service provider configuration.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - tenant (String.t): In a multi-tenant environment, where different tenants might connect to different identity providers, this parameter denotes the tenant to start a SAML flow for. In single-tenant environments this parameter is superfluous.
  - opts (KeywordList): [optional] Optional parameters
  ## Returns

  {:ok, nil} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec metadata(Tesla.Env.client(), String.t(), keyword()) ::
          {:ok, nil} | {:error, Tesla.Env.t()}
  def metadata(connection, tenant, _opts \\ []) do
    %{}
    |> method(:get)
    |> url("/saml/#{tenant}/metadata")
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {200, false},
      {500, false}
    ])
  end

  @doc """
  Create App Suite session after SAML login flow
  This API call is typically the result of a redirect created by the server. It does not need to be explicitly implemented by clients!  After a successful SAML login flow, the client (web browser) is redirected to this endpoint, where the actual App Suite session gets created. As a result, the user gets redirected to `https://<webmail-domain>/<login-path>#session=<session-id>`. The redirect response has App Suite session cookies set.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - token (String.t): A valid session reservation token
  - opts (KeywordList): [optional] Optional parameters
    - :client (String.t): Identifier of the client using the HTTP/JSON interface. Default: Value of configuration property `com.openexchange.ajax.login.http-auth.client`
    - :client_user_agent (String.t): Parameter to override the user agent used for session creation. By default the `User-Agent` request header is evaluated.
    - :login_path (String.t): The login path to be set on the resulting `Location` response header as part of the redirect response. Default: Value of configuration property `com.openexchange.UIWebPath`.
    - :shard (String.t): Shard identifier to route the requiest accordingly
  ## Returns

  {:ok, nil} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec saml_login(Tesla.Env.client(), String.t(), keyword()) ::
          {:ok, nil} | {:error, Tesla.Env.t()}
  def saml_login(connection, token, opts \\ []) do
    optional_params = %{
      :client => :query,
      :clientUserAgent => :query,
      :loginPath => :query,
      :shard => :query
    }

    %{}
    |> method(:get)
    |> url("/login?action=samlLogin")
    |> add_param(:query, :token, token)
    |> add_optional_params(optional_params, opts)
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {200, false},
      {302, false},
      {400, false},
      {403, false}
    ])
  end

  @doc """
  Terminates an App Suite session after SAML logout flow
  This API call is typically the result of a redirect created by the server. It does not need to be explicitly implemented by clients!  After a successful SAML logout flow, the client (web browser) is redirected to this endpoint, where the actual App Suite session gets terminated. As a result, the user gets usually redirected to an environment-specific location, for example a portal page. The redirect response removes all App Suite session cookies.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - session (String.t): App Suite session ID
  - opts (KeywordList): [optional] Optional parameters
  ## Returns

  {:ok, nil} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec saml_logout(Tesla.Env.client(), String.t(), keyword()) ::
          {:ok, nil} | {:error, Tesla.Env.t()}
  def saml_logout(connection, session, _opts \\ []) do
    %{}
    |> method(:get)
    |> url("/login?action=samlLogout")
    |> add_param(:query, :session, session)
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {200, false},
      {302, false}
    ])
  end

  @doc """
  Single Logout Service for Logout Requests
  SAML 2.0 Single Logout Service. Accepts `<LogoutRequest>` messages from the IdP per `HTTP-Redirect` binding.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - tenant (String.t): In a multi-tenant environment, where different tenants might connect to different identity providers, this parameter denotes the tenant to start a SAML flow for. In single-tenant environments this parameter is superfluous.
  - s_aml_request (String.t): Base64 encoded SAML 2.0 `<LogoutRequest>` message.
  - opts (KeywordList): [optional] Optional parameters
    - :sig_alg (String.t): Message signature algorithm ID
    - :signature (String.t): Message signature
    - :relay_state (String.t): Message exchange relay state
  ## Returns

  {:ok, nil} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec sls_req(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
          {:ok, nil} | {:error, Tesla.Env.t()}
  def sls_req(connection, tenant, s_aml_request, opts \\ []) do
    optional_params = %{
      :SigAlg => :query,
      :Signature => :query,
      :RelayState => :query
    }

    %{}
    |> method(:get)
    |> url("/saml/#{tenant}/sls")
    |> add_param(:query, :SAMLRequest, s_aml_request)
    |> add_optional_params(optional_params, opts)
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {200, false},
      {302, false},
      {400, false},
      {500, false}
    ])
  end

  @doc """
  Single Logout Service for Logout Responses
  SAML 2.0 Single Logout Service. Accepts `<LogoutResponse>` messages of the Single Logout Profile per `HTTP-POST` binding.

  ## Parameters

  - connection (OpenXchangeClient.Connection): Connection to server
  - tenant (String.t): In a multi-tenant environment, where different tenants might connect to different identity providers, this parameter denotes the tenant to start a SAML flow for. In single-tenant environments this parameter is superfluous.
  - u_nknownbasetype (UNKNOWN_BASE_TYPE):
  - opts (KeywordList): [optional] Optional parameters
  ## Returns

  {:ok, nil} on success
  {:error, Tesla.Env.t} on failure
  """
  @spec sls_resp(
          Tesla.Env.client(),
          String.t(),
          OpenXchangeClient.Model.UNKNOWN_BASE_TYPE.t(),
          keyword()
        ) :: {:ok, nil} | {:error, Tesla.Env.t()}
  def sls_resp(connection, tenant, u_nknownbasetype, _opts \\ []) do
    %{}
    |> method(:post)
    |> url("/saml/#{tenant}/sls")
    |> add_param(:body, :body, u_nknownbasetype)
    |> Enum.into([])
    |> (&Connection.request(connection, &1)).()
    |> evaluate_response([
      {302, false},
      {:default, false}
    ])
  end
end