esi-docs

OAuth 2.0 for Web Based Applications

Note: This document assumes you have read the basics of SSO authorization.

This document will cover the implementation details you will need to know for your web based application to be able to complete the OAuth 2.0 flow with EVE’s Single Sign On (SSO). This is required to access authenticated ESI routes.

Overview of OAuth 2.0 flow for web based Applications

When doing the OAuth 2.0 flow with the EVE SSO, web based applications should be using basic authentication.

Here is the OAuth 2.0 flow your web based application should be implementing:

Create a new application on the EVE SSO.
Store the Client ID and Secret Key assigned to your application somewhere that is accessible by your application. The Secret Key in particular needs to be stored securely and should never be shared.
Redirect your user to https://login.eveonline.com/v2/oauth/authorize/ with the following parameters in the query string. Make sure all strings placed in the URL are URL Encoded.
- response_type=code - This tells the EVE SSO what kind of response you are expecting from it, in this case you are letting it know you are starting the handshake for an authorization code.
- redirect_uri=<your application's defined callback> - Replace all text after the = with the full callback URL you defined for you application when creating a new application, make sure it is URL encoded (e.g. https%3A%2F%2Flocalhost%2Fcallback%2F). If you put in any other URL other than what is defined in your SSO application the EVE SSO will reject your request.
- client_id=<your application's client ID> - Replace all text after the = with the client ID assigned to your application that you stored somewhere in step 2.
- scope=<A URL encoded, space delimited list of ESI scopes you would like to request permissions for> - Replace all text after the = with a list of esi scopes split up by a single space that you would like to request permissions for (e.g. scope=esi-characters.read_blueprints.v1%20esi-corporations.read_contacts.v1).
- state=<something-unique> - Replace all text after the = with a unique string of your choice. state is required by EVE’s SSO to encourage extra security measures. A good explanation about how your application can be more secure with the use of the state parameter can be found here.
If you wanted access to a character’s blueprints and your callback URL was https://localhost/callback/ you would have a URL that looks something like this (anything surrounded by <> should be replaced by you, including <>): https://login.eveonline.com/v2/oauth/authorize/?response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2Fcallback%2F&client_id=<your-client-id>&scope=esi-characters.read_blueprints.v1&state=<unique-string>.
The EVE SSO will send a GET request to your application’s defined callback URL containing the query parameters code and state that looks like this (anything between <> will look different for you): https://<your-callback-url>/?code=<super-secret-code>&state=<unique-state-string-from-you>.

Your application needs to lift the value of the code query parameter from the URL so that it can be used in the next step. This authorization code is a one time use only token that has a lifetime of 5 minutes. If you do not respond within 5 minutes you will have to start over at step 1 again.
Now that your application has the authorization code, it needs to send a POST request to https://login.eveonline.com/v2/oauth/token with a payload containing the authorization code using Basic authentication where your application’s client ID will be the user and your secret key will be the password. Here is a little more detail on how to craft this request:

Create form encoded values that look like this (replace anything between <>, including <>):
```
  grant_type=authorization_code&code=<authorization code from callback URL>
```
Create a Base64 encoded string, including padding, where the contents before encoding are your application’s client ID, followed by a :, followed by your application’s secret key (e.g. Base64(<client_id>:<secret_key>)). For example, given the input CLIENT_ID:CLIENT_SECRET, the resulting string should be Q0xJRU5UX0lEOkNMSUVOVF9TRUNSRVQ=.
- You will need to send the following HTTP headers (replace anything between <>, including <>):
  - Authorization: Basic <Base64 encoded credentials>
  - Content-Type: application/x-www-form-urlencoded
  - Host: login.eveonline.com
Finally, send a POST request to https://login.eveonline.com/v2/oauth/token with your form encoded values and the headers from the last step.

If the previous step was done correctly, the EVE SSO will respond with a JSON payload containing an access token (which is a Json Web Token) and a refresh token that looks like this (Anything wrapped by <> will look different for you):
```
 {
     "access_token": <JWT token>,
     "expires_in": 1199,
     "token_type": "Bearer",
     "refresh_token": <unique string>
 }
```
For added security, before trusting the access_token and refresh_token, you should validate the access token to make sure it has not been tampered with in transit from the SSO to your application.

Once validated, your application will need to store both the access token and refresh token from this payload. Store the refresh token somewhere secure and never share it.

Note on security: the access token should also be stored securely but if it were to get leaked it can only be used for as long as is left of its 20 minute lifetime. If your refresh token gets leaked it can only be invalidated by you, the application developer, by revoking it. If you know your refresh token has been leaked you must revoke it.

The following diagram is a visual representation of the steps above. Any number between brackets ([]) is a reference to a step number in the list above:

Web based OAuth 2.0 Flow Diagram

If any of this is confusing, there is a code example available in Python that you can run locally to see this flow in action.

esi-docs

OAuth 2.0 for Web Based Applications

Overview of OAuth 2.0 flow for web based Applications

Further reading