The module provides two servlets which together create a service for exposing a key/hash scheme for access to OAuth scoped ESI endpoints. The ESI is a service provided by CCP which allows third party applications to access in game data for EVE Online.
Direct access to the ESI normally requires authenticating via OAuth. This can be inconvenient for certain applications (see below). The two servlets in this module together provide a proxy which accepts "key" and "hash" query parameters which are then translated into an OAuth access token before forwarding the request to the ESI. As a result, a much simpler authentication flow can be used for access to ESI data.
Originally, CCP provided an XML API for accessing in game data. This API used a simple key and hash to authenticate users. The simplicity of the scheme made the API easy to use from many different applications, but not very secure. Therefore, CCP decided to improve security by moving to an OAuth scheme for authenticating user access. This was deployed first for CREST and was used again for the ESI which is now the default supported API for access to game data from EVE Online third party applications. The XML API and CREST have been officially retired as of May 2018.
Endpoint security is now better, but the OAuth flow and the need to periodically refresh tokens is inconvenient for certain use cases, such as:
- Applications which can't or don't want to implement OAuth token refresh logic (e.g. non-interactive applications); or,
- Tools which don't support OAuth authentication for data sources (e.g. Google Sheets).
For these use cases, the key/hash scheme is easier to use.
The proxy provides the same Swagger-based interface used by the ESI servers, except that the usual OAuth authentication mechanism is replaced with a "key and hash" scheme. That is, you can call the usual ESI endpoints on the proxy, but instead of passing an authorization header with an access token, you instead pass two query arguments:
- esiProxyKey - a numeric key; and,
- esiProxyHash - an alphanumeric string.
The proxy uses these arguments to look up a properly refreshed access token which is then added to the call and forwarded to the ESI servers. The result of the ESI call is passed back to the proxy client. As long as your access tokens are not revoked, you'll be able to use your key/hash pair to access ESI endpoints.
The "key and hash" scheme used by the proxy is identical to the scheme used by the XML API endpoints and has the same security weakness, namely that anyone who has a copy of your key and hash can access any of your authenticated ESI endpoints (using this proxy). There are two ways you can protect against unintended use:
- You can choose to limit the set of ESI scopes accessible to a key/hash pair. This is done at key creation time; or,
- You can set an expiry date on a key/hash pair which disables the pair after a specified date.
The proxy retains your access token and attempts to refresh it until the key/hash pair expires. Any authorized third party application can do the same. So the proxy is no more or less safe than other third party applications which ask you to authenticate scopes.
If all else fails, you can directly revoke any access tokens you've granted to the proxy at the third party support site.
Once you standup an instance of the proxy (see instructions below), you can configure access as follows:
- Log in to the proxy website (this is standard EVE OAuth authentication using your configured client and secret key).
- Go to the "Connections" page and create a connection (you'll specify scopes and authenticate when you create the connection).
For each connection you create, the proxy will attempt to keep the access token refreshed each time you try to use the token (assuming the connection has not expired).
When you're ready to connect to the ESI, you'll use the proxy address in place of the ESI address. That is, you'll replace https://esi.tech.ccp.is/
with https://your.proxys.address/. The proxy supports all the same endpoints as the ESI. So for example https://esi.tech.ccp.is/latest/alliances/?datasource=tranquility
becomes https://your.proxys.address/latest/alliances/?datasource=tranquility.
If you're using an authenticated endpoint, you'll need to pass the appropriate key and hash from one of your connections. For example
https://your.proxys.address/latest/characters/12345/assets/?datasource=tranquility&esiProxyKey=..yourkey..&esiProxyHash=..yourhash..
If you're generating a Swagger client, you'll need to make a similar replacement to generate the proper URL for swagger.json. For example
https://esi.tech.ccp.is/latest/swagger.json?datasource=tranquility becomes
https://your.proxys.address/latest/swagger.json?datasource=tranquility.
Currently, the proxy supports all three available ESI servers ("legacy", "latest" and "dev"). However, we only regularly test against "latest".
If you want to stand up your own proxy, you can do so on a relatively modest machine. The steps are:
- Obtain an EVE SSO OAuth client key and secret at the EVE Developers site. The callback URL for your key will depend on how you configure
the proxy (see below). The proxy expects the callback URL to be
${enterprises.orbital.basepath}/${enterprises.orbital.appname}/api/ws/callback/eve. If you follow the instructions below and use the defaults, then the callback URL will end up ashttp://localhost:8080/esi-proxy/api/ws/callback/eve. - Create a database instance using your favorite JDBC and Hibernate compatible SQL database. By default, the proxy assumes you are using MySQL. You can change
to a different database vendor by using the appropriate Hibernate JDBC connector and modifying the JDBC driver settings in
/src/main/resources/META-INF/persistence.xml. You'll also need to create appropriate proxy tables on your database instance. This can be done in one of two ways:- Create the tables using the sample_schema.sql file in the top level directory of this module. You may need to customize this file according to the format expected by your database vendor; or,
- Let Hibernate create tables for you as needed. This can be done by adding
<property name="hibernate.hbm2ddl.auto" value="create"/>to your persistence.xml file. NOTE: be careful with table name case if you develop on MySQL on both Windows and Linux (as I do). Windows table names are case insensitive, but case matters on Linux. In order to make things work correctly, I set "lower_case_table_names = 1" in my.cnf on Linux MySQL.
- Follow the instructions below to create a proxy instance with access to your database instance. You'll want to verify authentication works correctly with EVE SSO Auth. You can find instructions for that on CCP's site here.
If everything has worked up to this point, then you now have a complete standalone instance of the proxy.
The proxy requires the setting and substitution of several parameters which control authentication, database and servlet settings. Since the frontend is normally built with Maven, configuration is handled by setting or overriding properties in your local Maven settings.xml file. The following configurations parameters should be set:
| Parameter | Meaning |
|---|---|
| enterprises.orbital.auth.eve_client_id | EVE Online SSO authentication client ID |
| enterprises.orbital.auth.eve_secret_key | EVE Online SSO authentication secret |
| enterprises.orbital.db.properties.url | Hibernate JDBC connection URL |
| enterprises.orbital.db.properties.user | Hibernate JDBC connection user name |
| enterprises.orbital.db.properties.password | Hibernate JDBC connection password |
| enterprises.orbital.db.properties.driver | Hibernate JDBC driver. Only necessary to change if you're not using MySQL |
| enterprises.orbital.db.properties.dialect | Hibernate JDBC dialec. Only necessary to change if you're not using MySQL |
| enterprises.orbital.swaggerui.model | URL for the proxy swagger config, e.g. https://your.proxys.address/api/swagger.json |
| enterprises.orbital.basepath | The base location where the servlet is hosted, e.g. http://localhost:8080 |
| enterprises.orbital.appname | Name of the servlet when deployed, e.g. esi-proxy |
| enterprises.orbital.proxyHost | Proxy host (used to substitute in ESI swagger.json), e.g. your.proxys.address |
| enterprises.orbital.proxyPort | Proxy port (used to substitute in ESI swagger.json), e.g. 443 |
Proxy authentication settings follow the conventions in the Orbital OAuth module.
To make debugging easier, we've added the property enterprises.orbital.auth.eve_debug_mode. When set to true, authenticating with EVE Online will always succeed
(EVE Online login servers are never actually invoked), and the logged in user will be named "eveuser". This mode allows you to develop and test when you're not
connected to a network, or otherwise don't want to have to go through the usual authentication flow every time.
At build and deploy time, the parameters above are substituted into the following files:
- src/main/resources/META-INF/persistence.xml
- src/main/resources/ESIProxy.properties
- src/main/webapp/WEB-INF/web.xml
If you are not using Maven to build, you'll need to substitute these settings manually.
We use Maven to build this module. Proxy dependencies are released and published to Maven Central, but we don't release the proxy itself. Instead, clone this repository and use "mvn install". Make sure you have set all required configuration parameters before building (as described in the previous section).
This project is designed to easily deploy in a standard Servlet container. Two parameters need to be substituted in the web.xml file in order for deployment to work correctly:
| Parameter | Meaning |
|---|---|
| enterprises.orbital.basepath | The base location where the servlet is hosted, e.g. http://localhost:8080 |
| enterprises.orbital.appname | Name of the servlet when deployed |
If you follow the configuration and build instructions above, these parameters will be substituted for you. These settings are used to define the base path for the REST API endpoints (via Swagger) needed for the frontend.
The default pom.xml in the project includes the Tomcat Maven plugin which makes it easy to deploy directly to a Tomcat instance. This is normally done by adding two stanzas to your settings.xml:
<servers>
<server>
<id>LocalTomcatServer</id>
<username>admin</username>
<password>password</password>
</server>
</servers>
<profiles>
<profile>
<id>LocalTomcat</id>
<properties>
<enterprises.orbital.tomcat.url>http://127.0.0.1:8080/manager/text</enterprises.orbital.tomcat.url>
<enterprises.orbital.tomcat.server>LocalTomcatServer</enterprises.orbital.tomcat.server>
<enterprises.orbital.tomcat.path>/esi-proxy</enterprises.orbital.tomcat.path>
</properties>
</profile>
</profiles>The first stanza specifies the management credentials for your Tomcat instance. The second stanza defines the properties needed to install into the server you just defined.
Make sure that enterprises.orbital.tomcat.path agrees with enterprises.orbital.appname as the former determines the path for your servlet.
With these settings, you can deploy to your Tomcat instance as follows (this example uses Tomcat 7):
mvn -P LocalTomcat tomcat7:deploy
If you've already deployed, use "redploy" instead. See the Tomcat Maven plugin documentation for more details on how the deployment plugin works.
The best way to get help is to raise an issue in our GitHub project.