Authentication
Most API calls, with only a few exceptions, require a client to have previously authenticated and obtained a session cookie from the EMS REST Proxy. To authenticate and obtain a session cookie, clients call POST /connect with the HTTP Authorization header set. Basic and Bearer authentication schemes are supported. In each case, the credentials provided are simply passed through to establish a connection to the EMS servers on behalf of the proxy client. The EMS REST Proxy does not itself make authentication or authorization decisions (aside from deciding whether to trust a client's TLS certificate, if configured to do so). It does not maintain or require a list of users and permissions, instead relying on the EMS server's configured users and permissions.
When logging in using the Basic scheme, simply provide a valid EMS username and password. For example,
curl -ks -X POST -b /tmp/cookies.txt -c /tmp/cookies.txt https://user:password@localhost:8080/connect
When using the Bearer scheme, provide a base64-encoded OAuth 2.0 access token. For example,
curl -ks -X POST -b /tmp/cookies.txt -c /tmp/cookies.txt https://localhost:8080/connect -H "Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyLwn5iyIjoiWW91IGRlY29kZWQgdGhpcz8gV2hhdCBhIG5lcmQhIPCfpJMifQ."
See Obtaining an Access Token in the EMS documentation for how to obtain an OAuth 2.0 access token.
Once a proxy client has successfully called POST /connect, a session cookie named ems is returned. All subsequent API calls must be made using this session cookie.
By default, if a client calls POST /connect without specifying any of the server_groups, server_group_tags, server_roles, or server_tags query parameters, then the client will be connected only to the EMS server group specified in the proxy's ems.default_server_group option. For example, to connect to both server groups 'group1' and 'group2', a client might call connect like this:
curl -ks -X POST -b /tmp/cookies.txt -c /tmp/cookies.txt https://user:password@localhost:8080/connect?server_groups=group1,group2
Once a client is connected and has established a proxy session, all subsequent API calls within that session will apply by default to all servers or server groups that were connected to during the initial POST /connect call. To target an API call to only a specific subset of servers or server groups, clients must use the server_groups, server_group_tags, server_roles, or server_tags query parameters as supported by the API being called. These query parameters can only narrow down the selection of servers or server groups the API call will apply to; they cannot be used to target servers or server groups that were not specified in the client's initial connect call. See Server Groups, Roles, and Tags for more detail.
Client Certificates (mTLS)
The EMS REST Proxy can additionally be configured to require client certificates using the proxy.require_client_certificate option. When requiring client certificates, a list of trusted client certificates or root certificates must also be configured using the proxy.trusted_client_certificates option. This list of trusted client certificates is often set to the same list the EMS server itself is configured to trust via its ssl_server_trusted option. The two lists are not required to be the same, however.