[HowTo] Setup SSO and ESI Fetching

[Salvoxia]

Hi guys,

this thread is intended as a how-to for setting up Single-Sign-On for your killboard and ESI killmail fetching.

Quick links to each paragraph:

• 1. Registering as developer with CCP
• 2. Registering your EDK installation with CCP
• 3. Configuring EDK
• 4. Registering a character for killmail fetching
• 5. ESI Fetch configuration and cron job

Best Regards,
Salvoxia

[Salvoxia]

1. Register your account as a developer (required for setting up SSO)

With the old XML API, you needed API keys for all pilots/corporations you wanted to fetch killmails for. Now, pilots or corporation directors have to register themselves using CCP's SingleSignOn (SSO) at your EDK and grant it access to character or corporation killmails via ESI.
To enable SSO for your killboard installation, you need to register it with CCP.
If you click the new "SSO Registration" link in your top menu, you will be greeted by a page like this:
[IMG]http://blindfish.info/kb_mods/4.3releas ... stered.jpg[/IMG]


Enter your Admin Control Panel and select "SSO Keys" on the right-hand menu:
[IMG]http://blindfish.info/kb_mods/4.3releas ... soKeys.jpg[/IMG]

Follow the link to EVE's developer page:
[IMG]http://blindfish.info/kb_mods/4.3releas ... rsLink.jpg[/IMG]

There, click the "Manage applications" button:
[IMG]http://blindfish.info/kb_mods/4.3releas ... sFront.jpg[/IMG]

Log in with the account you'd like to register this EDK installation with:
[IMG]http://blindfish.info/kb_mods/4.3releas ... sLogin.jpg[/IMG]

After logging in, you wil be directed back to the main Developers page. Again, select "Manage applications":
[IMG]http://blindfish.info/kb_mods/4.3releas ... sFront.jpg[/IMG]

If you have an valid account, you need to view and accept CCP's developer license:
[IMG]http://blindfish.info/kb_mods/4.3releas ... ration.jpg[/IMG]

Read the license, and if you accept it, click the "I agree" button:
[IMG]http://blindfish.info/kb_mods/4.3releas ... icense.jpg[/IMG]

[Salvoxia]

2. Register your EDK installation

After completing step 1, you will see an overview over all registered applications. Select "Create new application":
[IMG]http://blindfish.info/kb_mods/4.3releas ... erview.jpg[/IMG]

Enter a name and description for the killboard. This information will be displayed to anyone who will register for killmail fetching at your EDK installation.
For "Connection type", choose "Authentication & API Access".
In the "Permissions" section, search for "esi-killmails" in the left textbox, which will yield two results. Add them to the list of requested scopes by clicking on each.
[IMG]http://blindfish.info/kb_mods/4.3releas ... ion_01.jpg[/IMG]

For the "Callback URL" section, switch back to your browser tab showing your EDK Admin Control panel.
There, you can see the callback URL you need to insert in the Developer Application Registration:
Attention: If you switch to simple URLs (ACP -> Configuration -> Use simple URLs) or back, you'll have to update this callback URL in your application registration at CCP![/b]
[IMG]http://blindfish.info/kb_mods/4.3releas ... ackUrl.jpg[/IMG]

Copy that link and paste it into the "Callback URL" text field in the Developer Application Registration:
[IMG]http://blindfish.info/kb_mods/4.3releas ... ion_02.jpg[/IMG]

Finally, hit the "Create Application" button at the bottom of the page:
[IMG]http://blindfish.info/kb_mods/4.3releas ... ion_03.jpg[/IMG]

[Salvoxia]

3. Enter client ID and secret in EDK

After completing step 2, you will be redirected to your application overview, which now contains your newly registered EDK installation. Click the "View Application" button:
[IMG]http://blindfish.info/kb_mods/4.3releas ... cation.jpg[/IMG]

The application has been assigned a client ID and a client secret. Do NOT reveal the client secret to anyone!
Copy each value over to the tab with your EDK Admin Control Panel:
[IMG]http://blindfish.info/kb_mods/4.3releas ... etails.jpg[/IMG]
[IMG]http://blindfish.info/kb_mods/4.3releas ... Secret.jpg[/IMG]
Confirm by clicking the "Save" button.

[Salvoxia]

4. Registering a character with your EDK installation

Assume you want your killboard to fetch your character's killmails. In order to do that, select "SSO Registration" in your EDK top menu:
[IMG]http://blindfish.info/kb_mods/4.3releas ... ration.jpg[/IMG]

Select "Pilot" and click the "Login with EVE Online" button:
[IMG]http://blindfish.info/kb_mods/4.3releas ... gister.jpg[/IMG]

Now log in with the account containing the character you want to register:
[IMG]http://blindfish.info/kb_mods/4.3releas ... sLogin.jpg[/IMG]

Select the character from the drop down menu, then click the "Authorize" button
[IMG]http://blindfish.info/kb_mods/4.3releas ... racter.jpg[/IMG]

You will be redirected back to the SSO registration page of your EDK installation, where a success message should be displayed:
[IMG]http://blindfish.info/kb_mods/4.3releas ... sfully.jpg[/IMG]

Now, log back in to your Admin Control Panel and navigate to the SSO Keys page. It now will show the registered character along with information about that access token.

[Salvoxia]

5. ESI Fetch configuration and cron job

In ACP -> SSO Keys, there are a few preferences you can set.

• Maximum processing time per ESI SSO key [s]:
  This setting restricts the amount of time EDK may spend processing kills for a single SSO key. This is useful if you cannot influence the maximum execution time of your PHP installation, to make sure that each registered SSO key is processed.
• Ignore NPC only deaths?
  Like with the old API import, you can choose whether deaths to NPCs should not be imported.
• Only allow board owners to register?
  If this setting is enabled, only characters that are member of the alliances or corporations who are configured as board owners are allowed to register. If specific pilots are configured as board owners, only these pilots can register for ESI kill fetching.

As a replacement for the old cron_api.php CronJob, a new CronJob cron_esi.php was added. The recommended execution frequency is every five minutes.

For each SSO key, ESI Fetch will start fetching from the first killmails available up until it reaches the present. So it might take quite some time until you'll see current killmails on your killboard. Setting the appropriate cronjob to be executed every 5 minutes will speed up the process.

Enabling debug for ESI:
The ESI client library supports debug logging for all requests/replies sent to/received from ESI, including the response times. To enable debug logging, add the following line to your kbconfig.php file in your killboard's root directory:

Code: Select all

define('ESI_DEBUG', true);

The ESI debug.log file will be create in the cache/esi folder.