Skip to content

3rd party service provider setup

Jump to bottom
ronan edited this page Jul 27, 2021 · 4 revisions

App registration

You will need to register an application and generate client identifiers on the service providers developers portal before being able to authorize the Linx service:

  1. Log into the chosen service provider's developer console.

  2. Register a new connected/oauth application.

  3. Provide a 'Redirect' or 'Callback' url which is used to return the authorization code.

    To get this value without manually typing it out, make a request to the CallbackURL operation of your deployed Solution.

    This will return a string built up of the callback/redirect URL that you can then add to your app registration, for example:

    https://dev1.api.linx.twenty57.net/linxauth/callback

  4. Select and add any access scopes if necessary.

  5. Save your app.

  6. Generate a Client Secret.

  7. Copy the client identifiers (Client Id and Client Secret) and update them on your Linx server instance (see below)

Server configuration

Add the client identifiers to your Solutions config.

The Linx Solution is designed to use connection details for each of the service providers which are stored as JSON objects in files on the server drive.

When adding a new app configuration i.e. Google, GitHub, Microsoft, you will need to create the necessary config file with your unique client identifiers.

  1. On your main Linx Server dashboard, open the Solution, navigate to the Config Project (Left menu > Projects > Config).
  2. Locate the function specific to your service provider, i.e. the function WriteConfigFileGithub is configured specifically for writing out the connection details for the Github API.
  3. Click Run Function
  4. Complete the missing input parameters:
    • ClientId
    • ClientSecret
    • ClientScopes: If the chosen scopes differ from the default Solution then update this value. These scopes will need to be entered in the specified format specified in the service provider's documentation.
  5. Click RUN FUNCTION.

The service provider's new connection information will be written to a file on the server drive.

Service providers

The Linx solution has been setup to handle authentication with the below service providers:

Github API

App registration

  1. Navigate to your Github developer settings, OAuth apps section.
  2. Click New OAuth App
  3. Complete the details, adding the redirect url like described in the app registration section of this wiki.
  4. Save the app.
  5. Generate a new client secret.
  6. Copy the Client Id and Client secret and configure the Linx Solution like described above.

Implementation issues and considerations

User-Agent forbidden

A common issue that you may run into when working with the Github API is that you receive the below response:

Response code: 403 (Forbidden)
Response Body:
Request forbidden by administrative rules. Please make sure your request has a User-Agent header

This is a specific issue with the Github API, more details on the solution can be found here.

To resolve the issue, add the following as the User-Agent header when making requests to the Github API:

Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 YaBrowser/16.3.0.7146 Yowser/2.5 Safari/537.36

Useful resources:

Microsoft Graph API

App registration

  1. Go to the app registrations page on the Microsoft Azure Portal.
  2. Click on + New Registration.
  3. Give the app a name.
  4. For the Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
  5. In the Redirect URI section, add the redirect/callback url to the cloud server, like described in the app registration section of this wiki.
  6. Click Register.
  7. Open the Certificates & secrets tab from the left menu.
  8. Under the Client secrets section, click + New client secret.
  9. Add a description and expiry length.
  10. Click Add.
  11. Copy and save the Value of the new secret.
  12. Copy the Application ID (Client ID) from the overview page along with the client secret and configure the Linx Server with the new identifiers, as described in the server configuration section of this wiki.

Implementation issues and considerations

Tenant and organizational access

The levels of access varies depending on the tenant type, read more here. The default setup in this solution is 'common' which allows any user to be able to grant access but you can alter this when generating the necessary config file by altering the 'tenant id' input parameter during the server configuration.

Useful resources:

Google Cloud APIs

App registration

  1. Navigate to your Google developer console.
  2. Create a new Project.
  3. Select the new project.
  4. Open the Library from the left menu.
  5. Add and enable and relevant APIs that you will interact with.
  6. Navigate back to your main project dashboard.
  7. Open the Credentials tab from the left menu.
  8. Click on configure consent screen.
  9. Select the External user type and add your list of test users while the app is in development (for more info read here, then click create.
  10. Complete the basic details and continue.
  11. Add your scopes and save and continue.
  12. From the main dashboard, open the Credentials tab from the left menu. Click on CREATE CREDENTIALS > OAuth Client ID.
  13. For the Application type, select Web application.
  14. In the Authorized redirect URIs, add the redirect URL to the cloud server, like described in the app registration section of this wiki.
  15. Click create.
  16. Copy or download your client id and client secret.
  17. Configure the Linx Server with the new identifiers, as described in the server configuration section of this wiki.

Implementation issues and considerations

Scopes:

The Google APIs work as separate instances but share common scopes. When configuring the Linx solution with the app identifiers, you will need to update the ClientScopes input parameter to reflect your enabled APIs (a full list of scopes is available here)

Useful resources:

Salesforce API

App registration

  1. Login to your Salesforce instance.
  2. Open up the Setup.
  3. Navigate to Apps > App Manager in the left menu.
  4. Click New Connected App.
  5. Complete the basic details.
  6. Select Enable OAuth Settings
  7. Add the callback URL, like described in the app registration section of this wiki.
  8. Select your chosen scopes:
    • Access your basic information (id, profile, email, address, phone)
    • Full access (full)
    • Perform requests on your behalf at any time (refresh_token, offline_access)
  9. Click save & continue.
  10. Allow 10 minutes for the changes to take effect.
  11. In your apps overview page, look in down at the API section for your client identifiers.
  12. You will need to Click to reveal the secret.
  13. Copy the Consumer Key (Client ID) and Consumer Secret (Client Secret).
  14. Configure the Linx Server with the new identifiers, as described in the server configuration section of this wiki.

Implementation issues and considerations

Request Urls

Requests made to the Salesforce API must use a unique URL which is based on their instance name. This name needs to be retrieved using the Identity Url from Salesforce. This identity url can be retrieved by querying for user info with the access token string.

Useful resources:

Clone this wiki locally