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.
Refreshes the auto-login cookie.
Refreshes the secret cookie
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
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
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
change_ip(connection, session, client_ip, opts \\ [])
@spec change_ip(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.ChangeIpResponse.t()} | {:error, Tesla.Env.t()}
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
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
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
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
do_token_login(connection, auth_id, login, password, client_token, client, version, autologin, opts \\ [])
@spec do_token_login( Tesla.Env.client(), String.t(), String.t(), String.t(), String.t(), String.t(), String.t(), boolean(), keyword() ) :: {:ok, OpenXchangeClient.Model.TokenLoginResponse.t()} | {:error, Tesla.Env.t()}
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
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
orlogout
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 headerLocation
to the actual redirect URI.
- :flow (String.t): One of
returns
Returns
on success {:error, Tesla.Env.t} on failure
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
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
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
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
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 propertycom.openexchange.UIWebPath
. - :shard (String.t): Shard identifier to route the requiest accordingly
- :client (String.t): Identifier of the client using the HTTP/JSON interface. Default: Value of configuration property
returns
Returns
on success {:error, Tesla.Env.t} on failure
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