[WIP] LinkedIn endpoint and syndicator

[jackdbd]

This PR addresses issue #531

Warning

This PR is still a work in progress.

LinkedIn APIs, LinkedIn OAuth app, LinkedIn page

LinkedIn has several APIs (they call them API products).

In order to use any LinkedIn API we must create a LinkedIn OAuth app.

We also must associate a LinkedIn OAuth app with a LinkedIn page. However, we don't have to create a LinkedIn page ourselves, and we can use the Default Company Page (for API testing) instead.

Creating posts on LinkedIn

In order to create posts on LinkedIn we need to call the CREATE method of the LinkedIn Posts API. The CREATE method, like most other methods of this LinkedIn API, requires the OAuth 2.0 Authorization Code Flow (also called 3-legged OAuth). In order to create a LinkedIn post, the access token sent with the request needs to have the w_member_social scope.

The Posts API allows each LinkedIn OAuth app to create, each day, up to 500 posts per user, and up to 150,000 posts in total.

How to obtain an access token?

In production the user needs to go through the OAuth 2.0 flow. See example with simple-oauth2.

In development we can generate a LinkedIn access token using the OAuth Token Generator tool.

If you get this error in Chrome...

Oops. We can’t verify the authenticity of your request because the state parameter was modified

...try generating the token in Incognito mode as suggested here.

All access tokens issued by LinkedIn have an expiration of 60 days.

Useful links

• Linkedin API - How to get an OAuth access token and how to call the API - Step-by-step tutorial

[jackdbd]

At the moment this syndicator works, but relies on an access token created using the LinkedIn OAuth Token Generator Tool (the token has an expiration of 60 days).

Indiekit

1. The user writes a new note.

2. The user optionally assigns a slug.

3. The user decides that this note will be syndicated to LinkedIn (and Mastodon).

4. The user clicks the Syndicate post button in the detail page of the note.

5. The post appears on LinkedIn. TODO: how to format the text for LinkedIn (i.e. bold, links)?

6. The URL of the content syndicated to LinkedIn appears in the detail page of the note.

[jackdbd]

I created a new package endpoint-linkedin. This package includes the following routes:

1. oauth/linkedin: launches the Authorization Code Flow (3-legged OAuth).
2. oauth/linkedin/start: redirects to the consent screen of the LinkedIn OAuth app.
3. oauth/linkedin/callback: receives the LinkedIn request, extracts the authorization code and exchanges it for a LinkedIn access token. The LinkedIn access token is then persisted in the environment variable LINKEDIN_ACCESS_TOKEN.

The authorization flow starts when the user visits this page (I'm not very familiar with the codebase, so I just created a super simple view with nunjucks).

To quickly reach that page, I added a link in the welcome page.

When the user wants to allow Indiekit—or more precisely, the LinkedIn OAuth app they created for their Indiekit installation—they visit the authorization page on Indiekit, that redirects them to the LinkedIn consent screen.

Note: the user first needs to create a LinkedIn OAuth app with the required OAuth scopes and the required callback URL.

Tip

If the LinkedIn OAuth app is created with the scope openid, it also requires at least one another scope among profile and email. An app that has a openid scope issues both an access_token and an id_token.

[paulrobertlloyd]

Ooooh, I’ve longed thought about having UI-based OAuth for adding syndicators – this is so cool!

I think I’d be tempted to have this encapsulated in one plugin (plugins can provide endpoints as well a syndication methods, if needed).

I’d also be curious to know what, if anything, could be provided by Indiekit’s core (or a first-party plugin) to support building OAuth flows in the UI/application, so that this functionality could be added to other syndicators/content stores etc.

[jackdbd]

plugins can provide endpoints as well a syndication methods, if needed.

Yes, I think it makes sense to keep the endpoints for the OAuth flow and the syndication logic in the same plugin. I just didn't know how to organize the code in Indiekit.

so that this functionality could be added to other syndicators/content stores etc.

Absolutely. Most OAuth logic should be reusable across syndicators. I think most social networks (LinkedIn, Twitter, Reddit, etc) allow posting on the user's behalf using a OAuth 2.0 Authorization Code Flow (3-legged OAuth). I used the simple-oauth2 library to avoid implementing the entire OAuth 2.0 flow from scratch. I thought about putting the link to start the OAuth flow in the syndicator detail page: the user visits that page, gets redirected to the OAuth consent screen, clicks allow, returns the syndicator detail page. The user flow would be the same for other syndicators that require an OAuth flow.