OpenXchangeClient.Api.Login (open_xchange_client v0.10.1)

API calls for all endpoints tagged Login.

Link to this section Summary

Functions

Accesses a session that was previously created with the token login. This request allows clients to access a session created with the /login?action=tokenLogin request. When accessing the session its life time is extended equally to every other session.

Reuse old session saved in cookies by store request If the session ID was stored in a cookie before via the store request, the user can reuse his old session by using the autologin request.

Change IP of client host in a session. The following request is especially for integration with systems located in the providers infrastructure. If those systems create a session with the following request the client host IP address in the session can be changed. The IP check for following requests will be done using this newly set client host IP address.

Login to the web frontend using a simple HTML form. This request implements a possible login to the web frontend by only using a simple HTML form. The response contains a redirect link to the Web-UI. See OXSessionFormLogin for details. An example for such a form can be found in the backend's documentation folder (/usr/share/doc/open-xchange-core) under examples/login.html.

Login with user credentials. The login module is used to obtain a session from the user's login credentials. Parameters are normally expected in the POST request body.

Does the logout. Does the logout which invalidates the session.

Login for a very short living session. This request allows every possible client to create a very short living session. This session can then be transferred to any other client preferably a browser entering then the normal web interface. Then the sessions life time will be extended equally to every other session. Compared to the login mechanism using the random token, this request is more secure because two tokens are used. One of these tokens is only known to the client and one is generated by the server. Only the combination of both tokens allows to use the session. The combination of both tokens must be done by the client creating the session. DISCLAIMER: This request MUST NOT be used by some server side instance. If some server side instance uses this request to create a session for a browser on some client machine, then you have to transfer the full URL with server and client token over some connection to the client. This creates a VULNERABILITY if this is done. The token login method is only secure if this request is already sent from the same machine that later runs the browser using the created session.

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.

Redeem Token Login. With a valid session it is possible to acquire a secret (see token?action=acquireToken). Using this secret another system is able to generate a valid session. This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

Refresh auto-login cookie SECURITY WARNING! Utilizing this request is INSECURE! This request allows to access a session with a single one time token. This one time token may be delivered to the wrong client if the protocol has an error or Apache or the load balancer make a mistake. This will cause a wrong user to be in a wrong session. IMMEDIATELY consider not to use this request anymore. You have been warned. Use instead the FormLogin that does not need to use the redirect request.

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.

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.

Link to this section Functions

Link to this function

access_session(connection, server_token, client_token, client, opts \\ [])

@spec access_session(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, OpenXchangeClient.Model.TokensResponse.t()} | {:error, Tesla.Env.t()}

Accesses a session that was previously created with the token login. This request allows clients to access a session created with the /login?action=tokenLogin request. When accessing the session its life time is extended equally to every other session.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • server_token (String.t): The login name.
  • client_token (String.t): The password (MUST be placed in the request body, otherwise the login request will be denied).
  • client (String.t): Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
  • opts (KeywordList): [optional] Optional parameters

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

autologin(connection, opts \\ [])

@spec autologin(
  Tesla.Env.client(),
  keyword()
) :: {:ok, OpenXchangeClient.Model.LoginResponse.t()} | {:error, Tesla.Env.t()}

Reuse old session saved in cookies by store request If the session ID was stored in a cookie before via the store request, the user can reuse his old session by using the autologin request.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • opts (KeywordList): [optional] Optional parameters
    • :auth_id (String.t): Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request. (IS OPTIONAL, meaning can be empty)
    • :client (String.t): Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
    • :rampup (boolean()): Determines whether client specific rampup data should be returned with a successfull login request or not.
    • :rampup_for (String.t): Optional client identifier which is used to retrieve the rampup data.

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

change_ip(connection, session, client_ip, opts \\ [])

Change IP of client host in a session. The following request is especially for integration with systems located in the providers infrastructure. If those systems create a session with the following request the client host IP address in the session can be changed. The IP check for following requests will be done using this newly set client host IP address.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • session (String.t): A session ID previously obtained from the login module.
  • client_ip (String.t): New IP address of the client host for the current session.
  • opts (KeywordList): [optional] Optional parameters

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

do_form_login(connection, auth_id, login, password, client, version, autologin, opts \\ [])

@spec do_form_login(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  boolean(),
  keyword()
) :: {:ok, String.t()} | {:error, Tesla.Env.t()}

Login to the web frontend using a simple HTML form. This request implements a possible login to the web frontend by only using a simple HTML form. The response contains a redirect link to the Web-UI. See OXSessionFormLogin for details. An example for such a form can be found in the backend's documentation folder (/usr/share/doc/open-xchange-core) under examples/login.html.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • auth_id (String.t): Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
  • login (String.t): The login name.
  • password (String.t): The password.
  • client (String.t): Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange. If the autologin request should work the client must be the same as the client sent by the UI in the normal login request.
  • version (String.t): Used version of the HTTP/JSON interface client.
  • autologin (boolean()): True or false. True tells the UI to issue a store request for the session cookie. This store request is necessary if you want the autologin request not to fail.
  • opts (KeywordList): [optional] Optional parameters
    • :rampup (boolean()): Determines whether client specific rampup data should be returned with a successfull login request or not.
    • :rampup_for (String.t): Optional client identifier which is used to retrieve the rampup data.
    • :ui_web_path (String.t): Defines another path on the web server where the UI is located. If this parameter is not defined the configured default of the backend is used.
    • :client_ip (String.t): IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP client doing this request is used.
    • :client_user_agent (String.t): Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

do_login(connection, name, password, opts \\ [])

@spec do_login(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
  {:ok, OpenXchangeClient.Model.LoginResponse.t()} | {:error, Tesla.Env.t()}

Login with user credentials. The login module is used to obtain a session from the user's login credentials. Parameters are normally expected in the POST request body.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • name (String.t): The login name.
  • password (String.t): The password (MUST be placed in the request body, otherwise the login request will be denied).
  • opts (KeywordList): [optional] Optional parameters
    • :auth_id (String.t): Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request. (IS OPTIONAL, meaning can be empty)
    • :rampup (boolean()): Determines whether client specific rampup data should be returned with a successfull login request or not.
    • :rampup_for (String.t): Optional client identifier which is used to retrieve the rampup data.
    • :client (String.t): Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
    • :version (String.t): Used version of the HTTP/JSON interface client.
    • :client_ip (String.t): IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP client doing this request is used.
    • :client_user_agent (String.t): Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

do_logout(connection, session, opts \\ [])

@spec do_logout(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Tesla.Env.t()}

Does the logout. Does the logout which invalidates the session.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • session (String.t): A session ID previously obtained from the login module.
  • opts (KeywordList): [optional] Optional parameters

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

do_token_login(connection, auth_id, login, password, client_token, client, version, autologin, opts \\ [])

Login for a very short living session. This request allows every possible client to create a very short living session. This session can then be transferred to any other client preferably a browser entering then the normal web interface. Then the sessions life time will be extended equally to every other session. Compared to the login mechanism using the random token, this request is more secure because two tokens are used. One of these tokens is only known to the client and one is generated by the server. Only the combination of both tokens allows to use the session. The combination of both tokens must be done by the client creating the session. DISCLAIMER: This request MUST NOT be used by some server side instance. If some server side instance uses this request to create a session for a browser on some client machine, then you have to transfer the full URL with server and client token over some connection to the client. This creates a VULNERABILITY if this is done. The token login method is only secure if this request is already sent from the same machine that later runs the browser using the created session.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • auth_id (String.t): Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
  • login (String.t): The login information.
  • password (String.t): The password (MUST be placed in the request body, otherwise the login request will be denied).
  • client_token (String.t): Client side identifier for accessing the session later. The value should be some token that is unique for every login request.
  • client (String.t): Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
  • version (String.t): Version of the HTTP/JSON interface client. Only for statistic evaluations.
  • autologin (boolean()): '’True’ or ’false’. True tells the UI to issue a store request for the session cookie. This store request is necessary if you want the autologin request not to fail. This must be enabled on the server and a client can test with the autologin request if it is enabled or not.'
  • opts (KeywordList): [optional] Optional parameters
    • :ui_web_path (String.t): Defines another path on the web server where the UI is located. If this parameter is not defined the configured default of the backend is used.
    • :client_ip (String.t): IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP client doing this request is used.
    • :client_user_agent (String.t): Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.
    • :json_response (boolean()): ’True’ or ’false’ (default). Defines the returned data type as JSON. Default false will return a redirect.

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

init(connection, tenant, opts \\ [])

@spec init(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil}
  | {:ok, OpenXchangeClient.Model.InlineResponse2003.t()}
  | {:error, Tesla.Env.t()}

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

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

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

redeem_token(connection, auth_id, token, client, secret, opts \\ [])

@spec redeem_token(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, OpenXchangeClient.Model.LoginResponse.t()} | {:error, Tesla.Env.t()}

Redeem Token Login. With a valid session it is possible to acquire a secret (see token?action=acquireToken). Using this secret another system is able to generate a valid session. This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • auth_id (String.t): Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
  • token (String.t): The token created with token?action=acquireToken.
  • client (String.t): Identifier of the client using the HTTP/JSON interface. The client must identifier must be the same for each request after creating the login session.
  • secret (String.t): The value of the secret string for token logins. This is configured through the tokenlogin-secrets configuration file.
  • opts (KeywordList): [optional] Optional parameters

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

redirect(connection, random, opts \\ [])

@spec redirect(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, OpenXchangeClient.Model.CommonResponse.t()} | {:error, Tesla.Env.t()}

Refresh auto-login cookie SECURITY WARNING! Utilizing this request is INSECURE! This request allows to access a session with a single one time token. This one time token may be delivered to the wrong client if the protocol has an error or Apache or the load balancer make a mistake. This will cause a wrong user to be in a wrong session. IMMEDIATELY consider not to use this request anymore. You have been warned. Use instead the FormLogin that does not need to use the redirect request.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • random (String.t): A session random token to jump into the session. This random token is part of the login response. Only a very short configurable time after the login it is allowed to jump into the session with the random token.
  • opts (KeywordList): [optional] Optional parameters
    • :client (String.t): The client can be defined here newly if it is not correct on the login request itself.
    • :store (boolean()): Tells the UI to do a store request after login to be able to use autologin request.
    • :ui_web_path (String.t): The optional path on the webserver to the UI. If this parameter is not given the configured uiWebPath is used.

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

refresh_auto_login_cookie(connection, session, opts \\ [])

@spec refresh_auto_login_cookie(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, OpenXchangeClient.Model.CommonResponse.t()} | {:error, Tesla.Env.t()}

Refreshes the auto-login cookie.

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • session (String.t): A session ID previously obtained from the login module.
  • opts (KeywordList): [optional] Optional parameters

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

refresh_secret_cookie(connection, session, opts \\ [])

@spec refresh_secret_cookie(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, OpenXchangeClient.Model.CommonResponse.t()} | {:error, Tesla.Env.t()}

Refreshes the secret cookie

parameters

Parameters

  • connection (OpenXchangeClient.Connection): Connection to server
  • session (String.t): A session ID previously obtained from the login module.
  • opts (KeywordList): [optional] Optional parameters

returns

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

saml_login(connection, token, opts \\ [])

@spec saml_login(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Tesla.Env.t()}

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

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

Returns

on success {:error, Tesla.Env.t} on failure

Link to this function

saml_logout(connection, session, opts \\ [])

@spec saml_logout(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Tesla.Env.t()}

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

Parameters

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

returns

Returns

on success {:error, Tesla.Env.t} on failure