How to set up OpenID Connect proxy in FTW

The OpenID Connect (OIDC) support in Flex allows you to integrate login solutions that do not necessarily implement OpenID Connect. The idea is to build a suitable login flow in FTW and wrap that login information into an OpenID Connect ID token that can be used to validate user login in Flex. With this approach, FTW will serve as an identity provider towards Flex.

Flex verifies the ID token by fetching the JSON Web Key that is hosted by your FTW server and using that to unsign the token. A consequence of this is, that the JSON Web Key needs to be publicly available. This means that the proxy setup will not work directly in localhost. To test out the LinkedIn login, you should e.g. deploy your FTW changes to Heroku.

In this guide, we'll integrate LinkedIn login to Flex by using FTW as an OIDC proxy to Flex. The main steps to take to achieve this are:

1. Create a login app in Linkedin
2. Configure a new identity provider and client in Flex Console
3. Build LinkedIn login flow in FTW
4. Proxy the successful LinkedIn login information to Flex in OIDC format

Note, that using FTW as an OpenID Connect proxy requires ftw-daily version 7.3.0 or ftw-hourly version 9.3.0.

A note about development environments

For OpenID Connect (OIDC) identity providers, Flex supports RSA signed ID tokens. RSA is an asymmetric signing function. Therefore, all OIDC identity providers will need to provide their URL (also known as issuer location) to Flex so that public signing keys can be fetched for ID token validation. When using FTW as an OIDC proxy, FTW should be served publicly, so that Flex can fetch the public signing key used to sign ID tokens used with authentication. This means that when developing OIDC proxy capabilities, by default, an FTW application running in localhost can not be used as an OIDC proxy but the application should be deployed, for example, to a staging environment. If you desire to develop this functionality complete locally, take a look at tools like Ngrok or Localtunnel that allow exposing your local ports publicly.

Create a login app in LinkedIn

1. Head to LinkedIn apps management page. A LinkedIn account is required.
2. Click "Create app"
3. Add app name
4. Search the LinkedIn page of your marketplace business. If you do not have a LinkedIn page, you can create one by selecting "+ Create a new LinkedIn Page".
5. Fill in the URL to the privacy policy in your marketplace.
6. Add a logo.
7. Check the legal agreement and you are ready to click "Create app"
8. Navigate to the Auth tab in your new app view.
9. Add a new redirect URL: <your marketplace URL>/api/auth/linkedin/callback. So for example, https://www.mymarketplace.com/api/auth/linkedin/callback
10. Make a note of the client ID and client secret. You will need these values later on.
11. Move to the Products tab and add Sign In with LinkedIn by clicking "Select" by the product.
12. It takes a few moments for LinkedIn to validate your app for the Sign In product.

Configure a new identity provider and client in Flex Console

With this proxy implementation, your FTW works as the identity provider that Flex uses to validate the ID token that wraps the LinkedIn login information. To enable logins in Flex using the OIDC proxy, a corresponding identity provider and identity provider client need to be configured for your marketplace in Flex Console. See the OpenID Connect cookbook on for information on how to add a new identity provider for your marketplace.

Here's some guidance for configuring a new identity provider and a client to be used as a proxy for LinkedIn:

• Identity provider name and ID The identity provider ID is generated based on the name of the IdP. The ID will be passed to the Flex API when creating a user or logging in using the proxy. When a user logs in with an identity provider, their identity provider profile is linked to their user account and this relationship is exposed in the currentUser resource in the Flex API. If the intention is to use the FTW to proxy login to multiple services, it's advised to create a distinct identity provider for each, and name them so that the ID indicates what is the actual service providing the authentication. In LinkedIn's case the IdP name could be "LinkedIn" or "LinkedIn Proxy".
• Identity provider URL Based on this URL, Flex determines the path to an OpenID Connect discovery document ([identity provider URL]/.well-known/openid-configuration) and from there on to an ID token signing key. By default this should be the root address of your application, for example, https://myexampleapp.com or, for default Heroku URLs, https://MYEXAMPLEAPP.herokuapp.com. Note, that this URL needs to be publicly hosted so a localhost URL will not work.
• Client ID When using FTW as on OpenID Connect proxy, you are in charge of generating a client ID. The value can be any randomly generated string.

Build LinkedIn login flow in FTW

FTW as an OpenID Connect identity provider

FTW-daily and FTW-hourly provide a few helper functions which you can use as a starting point in your customization. When following this guide you will not need to pay too much attention to them as the crucial code is provided for you in the linkedin.js file below but it's good to be aware of them. You can find these functions in the api-util/idToken.js file in your server:

└── server
    └── api-util
          └── idToken.js
          ...

createIdToken

Turns information fetched from a 3rd party identity provider (e.g. LinkedIn) info a signed JSON Web Token (JWT).

This function expects three parameters: idpClientId, user and options.

• idpClientId is the client id of your custom identity provider you have set up in Console:
• user object should contain at least firstName, lastName, email and emailVerified fields.
• options object contains information about how the id token should be signed and the keys required for that. Currently, Flex supports only RS256 signing algorithm so the options object should look like this:

{ signingAlg: 'RS256', rsaPrivateKey, keyId }

openIdConfiguration and jwksUri

These functions can be used to serve an OpenID Connect discovery document and JSON Web Keys that are used by Flex to validate the ID token written by your proxy implementation. FTW will automatically use these functions to expose correct endpoints when JWT signing keys are configured.

Build LinkedIn signup flow to FTW’s backend (using passport.js)

We are using Passport.js library for handling the authentication with different identity providers like with Facebook and Google. The library offers multiple authentication strategies and there's also a strategy for Linkedin which we are going to use in this example.

Environment variables

First up, we'll need to define some new environment variables.

REACT_APP_LINKEDIN_CLIENT_ID and LINKEDIN_CLIENT_SECRET

Set these as the client ID and client secret of your LinkedIn app.

RSA_PRIVATE_KEY and RSA_PUBLIC_KEY

The ID token is signed with an RSA key. You can, for example, use a command line tool like ssh-keygen to generate the keys. Note, that when storing the keys in an environment variable file, you should replace any line brakes with \n. However, for example in Heroku, the environment variables should include all line breaks. You should also make sure that the key size is big enough.

LINKEDIN_PROXY_IDP_ID

The identifier of your identity provider that you configure to Flex. It declares that you are using your FTW OpenID Connect proxy as an identity provider. Use the "IdP ID" value of an identity provider client in Console for this variable.

LINKEDIN_PROXY_CLIENT_ID

The client ID of your identity provider client that you configure to Flex. Use the "Client ID" value of an identity provider client in Console for this variable.

KEY_ID

The value will be used as the kid header in ID tokens that are passed to Flex when a user logs in with LinkedIn. It is also used as the kid attribute of the JSON Web key that the proxy serves in an endpoint. Even though using a kid value in your keys is not compulsory, we heavily recommend using it with your token and the JWK. For example, key caching in the Flex API relies heavily on it.

Passport module dependency

Add the following entry to the dependencies map in package.json and run yarn install:

"passport-linkedin-oauth2": "^2.0.0",

LinkedIn login flow

Next, let's add a new file to FTW that handles authentication to LinkedIn. You can find the complete file here:

• linkedin.js

Place the file in server/api/auth folder inside FTW:

└── server
    └── api
        └── auth
            └── linkedin.js

The biggest difference between LinkedIn login and e.g. Facebook login which has first-class support in Flex is that we need to use createIdToken helper function to create the id token from the information we fetched from LinkedIn. This new id token is then passed forward to Flex as idpToken parameter.

  createIdToken(idpClientId, user, { signingAlg: 'RS256', rsaPrivateKey, keyId })
    .then(idpToken => {
      const userData = {
        email,
        firstName,
        lastName,
        idpToken,
        from,
        defaultReturn,
        defaultConfirm,
      };
      done(null, userData);
    })
    .catch(e => console.error(e));
};

Now we'll need to expose login endpoints that invoke functions provided by the linkedin.js file.

In server/apiRouter.js, add the following import:

const {
  authenticateLinkedin,
  authenticateLinkedinCallback,
} = require('./api/auth/linkedin');

And after all the router.* invocations, add LinkedIn login routes:

// This endpoint is called when the user wants to initiate authentication with Linkedin
router.get('/auth/linkedin', authenticateLinkedin);

// This is the route for callback URL the user is redirected after authenticating
// with Linkedin. In this route a Passport.js custom callback is used for calling
// loginWithIdp endpoint in Flex API to authenticate user to Flex
router.get('/auth/linkedin/callback', authenticateLinkedinCallback);

Finally, on the server side we need to update server/api/auth/createUserWithIdp.js so that a correct IdP client ID is passed to the Flex API. In the beginning of the file resolve the following environment variables:

const LINKEDIN_PROXY_CLIENT_ID = process.env.LINKEDIN_PROXY_CLIENT_ID;
const LINKEDIN_PROXY_IDP_ID = process.env.LINKEDIN_PROXY_IDP_ID;

And update the logic that resolves the idpClientId variable:

const idpClientId =
  idpId === FACEBOOK_IDP_ID
    ? FACBOOK_APP_ID
    : idpId === GOOGLE_IDP_ID
    ? GOOGLE_CLIENT_ID
    : idpId === LINKEDIN_PROXY_IDP_ID
    ? LINKEDIN_PROXY_CLIENT_ID
    : null;

Add LinkedIn-button to FTW

Once we have added the authentication endpoints to the FTW server, we need to add a button for LinkedIn login to the AuthenticationPage.

└── src
    └── containers
        └── AuthenticationPage

We can once more use the existing Google and Facebook login code as an example an create a similar authWithLinkedin function, which adds the default URL parameters to the API call and then redirects user to the authentication endpoint.

const authWithLinkedin = () => {
  const defaultRoutes = getDefaultRoutes();
  const {
    baseUrl,
    fromParam,
    defaultReturnParam,
    defaultConfirmParam,
  } = defaultRoutes;
  window.location.href = `${baseUrl}/api/auth/linkedin?${fromParam}${defaultReturnParam}${defaultConfirmParam}`;
};

Then we can use the SocialLoginButton component to show the option to log in with LinkedIn to the users. Remember to add the LinkedIn related translation keys as well as LinkedIn logo too! Usually, different identity providers have brand centers where you can find the logos and guidelines how to use them. You can download LinkedIn logo from LinkedIn brand center.

const linkedinButtonText = isLogin ? (
  <FormattedMessage id="AuthenticationPage.loginWithLinkedIn" />
) : (
  <FormattedMessage id="AuthenticationPage.signupWithLinkedIn" />
);

<div className={css.socialButtonWrapper}>
  <SocialLoginButton onClick={() => authWithLinkedin()}>
    <span className={css.buttonIcon}>{LinkedinLogo}</span>
    {linkedinButtonText}
  </SocialLoginButton>
</div>

In the AuthenticationPage component, the idp const defines what is presented as the name of the identity provider in the sign up confirm page. By default, it uses the IdP ID stored in a cookie with a capitalized first letter. In case that is not sufficient approach given the IdP ID in use, a custom name for the identity provider can be used by, for example, by comparing the IdP ID in the cookie to the one used by your proxy IdP and overriding the default when suitable.

That's it! In order to integrate some other identity provider, implement their authentication flow using Passport.js or some other method and use the utility functions in api-util/idToken.js accordingly to wrap the login information into an OpenID Connect ID token that can be used to log in to a Flex marketplace.