Information on changes to ESI for Third Party Applications

Today some changes to ESI were deployed, which may have caused some issues with third party applications that were not up to date. Although these changes were announced in a dev blog earlier this month, due to issues with the developers.eveonline.com website rendering blogs inaccessible it may not have been properly communicated to all third party developers and we apologise for this. We have had reports from players for some third party applications failing, so we are reproducing the contents of the blog here for developers:


UPDATE: Due to a case of PEBCAK I reproduced the wrong blog in OP. The change deployed today affected a different aspect of ESI. The information originally posted on developers.eveonline.com pertaining to today’s deployment follows:

On 30 July 2020 in the ESI changelog we announced the deprecation of v4 version characters/{character_id}  ESI route on 15 September and subsequent removal on 21 September. Unfortunately we still see heavy traffic hitting that route which as of now has legacy status. Accordingly we’ve decided to postpone the (admittedly quite abrupt) removal. Its been rescheduled and now it will happen on 21st October 2021.  Please spread that information if you know any developer that might not follow changelog and/or Tweetfleet.

Please visit esi-issues/changelog.md at master · esi/esi-issues · GitHub for more details.

However the originally reproduced dev blog below is also scheduled to take place on 1 November for your information:


Deprecating obsolete endpoints

The old OAuth endpoints oauth/authorize, oauth/token and oauth/verify will be deprecated. You should move your application over to v2/oauth/authorize and v2/oauth/token instead. The oauth/verify endpoint will also be deprecated, since the v2 endpoints return a JWT token, enabling your applications to validate the JWT tokens without having to make a request to the SSO for each token. Applications can fetch the required EVE SSO metadata from https://login.eveonline.com/.well-known/oauth-authorization-server to be able to validate JWT token signatures client-side.

What about our old refresh tokens?

Existing applications can do a one-way-upgrade on their existing refresh tokens by sending them to the v2/oauth/token instead of oauth/token endpoint to upgrade them to v2 tokens. Make sure to replace the stored refresh token with the one returned in the response! Once an old refresh token is upgraded to a v2 token, the old token is invalidated and no longer usable. This upgrade mechanism will only be active for two weeks after the release.

You can tell the new refresh tokens apart from the old ones as they are a 24 character strings (16 bytes Base64 encoded).

V2 Refresh token example: MDEyMzQ1Njc4OWFiY2RlZg==

Stricter OAuth conformance

Developers will need to follow the OAuth specification more closely when sending data to the SSO token endpoint. In short, to ensure that your application continues to work with the EVE SSO, you should follow the official EVE SSO guidelines.

Here are some important points to be aware of:

  • Native/mobile applications should use the PKCE flow as described here.
  • Web/server-side applications should use the authorization code flow as described here.
  • The v2/oauth/token endpoint will no longer accept data sent as a JSON payload or as a URL query. Data must be sent to the endpoint with Content-Type: application/x-www-form-urlencoded and encoded as such in accordance with Section 4.1.3 in OAuth RFC (6749).

Correct:

POST v2/oauth/token HTTP/1.1
Host: login.eveonline.com
Content-Type: application/x-www-form-urlencoded

client_id=someawesomeclient&grant_type=authorization_code&code=exampleauthorizationcode&code_verifier=codeverifier&redirect_uri=https%3A%2F%2Fmy3rdpartyapp%2Fauth%2Fcallback

Incorrect - Data sent as a JSON payload:

POST v2/oauth/token HTTP/1.1
Host: login.eveonline.com
Content-Type: application/json

{ "client_id":"someawesomeclient","grant_type":"authorization_code","code":"exampleauthorizationcode","code_verifier":"codeverifier","redirect_uri":"https://my3rdpartyapp/authþ/callback"}

Incorrect - data sent as a querystring:

POST v2/oauth/token?client_id=someawesomeclient&grant_type=authorization_code&code=exampleauthorizationcode&code_verifier=codeverifier&redirect_uri=https%3A%2F%2Fmy3rdpartyapp%2Fauth%2Fcallback HTTP/1.1
Host: login.eveonline.com

Use a standardized OAuth JWT validation library

Developers should use a standard OAuth JWT validation library to be prepared for upcoming changes in the SSO such as different JWT signature methods. Libraries exist for pretty much all programming languages out there. See JWT.IO for more information and an SDK for your programming language of choice!

Prepare for refresh token rotations

Developers have until now been able to safely assume that their stored refresh tokens will never change. This will no longer be the case, so developers should assume that the refresh token MIGHT change when it is refreshed and update it when needed.

Rate limits for failed requests

We'll be introducing a rate-limiter that will kick in when an application exceeds a certain threshold of failed requests. When it is triggered a 429 Too Many Requests response will be returned. This is to encourage developers to clear old/invalid refresh tokens from their databases as well as make sure their applications are well tested and conform to the OAuth specification. Applications that repeatedly trigger the rate-limiting and don't respect the Retry-After header might get their applications blocked by the EVE SSO for API Abuse and require a support ticket to be reopened

2 Likes

Developers have until now been able to safely assume that their stored refresh tokens will never change. This will no longer be the case, so developers should assume that the refresh token MIGHT change when it is refreshed and update it when needed.

How resilient will this be? Will the old refresh_token be immediately invalidated, or will calls that happen within the same second be OK (or fail)?

2 Likes

Given no effective notice, the magnitude of changes required to utilize the new endpoints, convert tokens and deploy to many installations, is it possible to rollback the change for 60 days?

2 Likes

Today some changes to ESI were deployed which may have caused some issues with SSO for third party applications that were not up to date.

Can you please by more specific? Are saying that the SSO v1 token have not already been deprecated, 1 week ahead of the original schedule?

I mistakenly reproduced the wrong blog in OP but I have updated it with the correct notification that was originally provided on developers.eveonline.com earlier this month. I have left the reproduction of the other blog underneath.

1 Like

This time, it’s the v4 character endpoint which has been disabled. not Oauth. (that’s still going to be a concern come november)

To confirm, the only change made today (after delays) was the removal of /v4/characters/
{character_id}.

2 Likes

OP updated to remove references to SSO with today’s update.

Would CCP please kindly take these words at heart for their own applications and developments? If not, can we please have a rate limiter for bad features per month?

When will developer registration be fixed? It’s been broken for well over a week now, and you’ve barely even acknowledged the issue, let alone any timeline for it being resolved.

2 Likes

Please also note the ESI changelog here esi-issues/changelog.md at master · esi/esi-issues · GitHub

Any timeline on a fix for this CCP?

Hi there - we are aware that developer registration is still down at the moment.

The problem is being looked into, we’ll post updates as we know more.

1 Like

There is a bug with 1 scope not working at all (can’t tell if any other scopes may be affected) after this change: esi-universe.read_structures.v1 scope not working · Issue #1302 · esi/esi-issues · GitHub

Or maybe the scope got renamed and its not updated everywhere?
:pray:

Please. It’s been weeks. Cart before horse kind of situation here. Can’t even consider new ESI implementation without access as a developer.

Is there something like a esipy module for python that works with the new changes?

It appears the Pathfinder was effected. My Corp and myself use Pathfinder extensively and it (Pathfinder) is blocking logins. This is the type of stuff that is ruinous to reputations and confidence.

See Pathfinder v2.4.1 : evetech.

1 Like