...

OAuth2 is a authentication method allowing users to access a website without setting up credentials with that website. In lieu of credentials, trust between the website and the user are established via some third-party identity provider, such as Microsoft. Okta, Google, Amazon, Facebook, GitHub, etc.. Trust is established in the form of token exchanges, which happen transparently to the user, and typically browser cookies.

That trust can be also expanded to the Profound API server via OAuth2. A Profound API server can be setup to authenticate a user's OAuth2 token, and only respond to API requests when a valid token is present. This capability allows services already using OAuth2 to take advantage of Profound API without needing to invent another trust mechanism between that service and the Profound API server.

...

• x-cacheTokenTTL – a number specifying how long in seconds to cache a user’s validated ID string before re-validating their username with the OAuth2 provider.

  • A value of 0 means that each API request will cause a request to be made to the OAuth2 provider to validate the user.

  • Default: 300 (5 minutes).

  • Set this to a reasonable value for your organization, where too low can slow down API responses and result in unnecessary network traffic, but too high can result in users remaining validated too long after their session or token has ended or expired.

Example excerpts

These include working URLs for User-Validation APIs (as of August 25, 2023):

Microsoft Examples showing minimum properties needed for validating PAPI requests via OAuth2 are below. If you need to setup Profound.js as an authentication server to let users sign on, then see the section, “Sample Workspace for OAuth2 Sign-On”.

Microsoft Entra (Azure Active Directory)

...

      "OAuth2_GitHub": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "x-userinfoUrl": "https://api.github.com/user",
            "x-userinfoField": "login"
          }
        }
      },

Note: the URLs above are valid for User-Validation APIs as of August 30, 2023.

Security Rules

The “security” object inside of the openapi.json file determines which security schemes are used for requests, and whether one or all must be valid before a request is authorized. (See OpenAPI Configuration under “Multiple Security Schemes” for more information.)

Example Excerpt excerpt where requests matching EITHER “OAuth2_MS_Entra_Identity” OR “ApiKeyAuth” are permitted.

  "security": [
    {
      "OAuth2_MS_Entra_Identity": []
    },
    {
      "ApiKeyAuth":  []
    }

Complete Example openapi.json

...

...

Example excerpt where requests must match BOTH OAuth2_MS_Entra_Identity and ApiKeyAuth , or else the API returns a Not validated response:

"security": [
  {
    "OAuth2_MS_Entra_Identity": [],
    "ApiKeyAuth": []
  }
]

Complete Example openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "APIs",
    "version": "1.0.0"
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "OAuth2_MS_Entra_Identity": {
        "type": "oauth2",
        "description": "Microsoft Azure Active Directory (Entra)",
        "flows": {
          "authorizationCode": {
            "x-userinfoUrl": "https://graph.microsoft.com/v1.0/me",
            "x-userinfoField": "userPrincipalName"
          }
        }
      }
    }
  },
  "x-allowAnonymous": false,
  "security": [
    {
      "OAuth2_MS_Entra_Identity": []
    },
    {
      "ApiKeyAuth": []
    }
  ]
}

Note: the x-allowAnonymous property must be false in order for API security to function properly.

Conventions

By default, Profound API expects certain conventions with OAuth2:

...

If you do not already have a /modules/oauth2sample/ workspace in your Profound.js server installation, then you can install it with the following shell command, from within the installation directory of your Profound.js instance:

node complete_install --configureThe installSamples

If you do not already have a config.js file, then the script will prompt for various settings. When asked to install sample code, answer yes, `y`, then answer `y` when prompted about oauth2sample y for yes. For example your terminal screen may look like below:

$ cd /c/profoundjs
$ node complete_install --configureinstallSamples

Specify port number for Profound.js server (8081):
Install with Git integration (n)?
Install sample code (y)?
Install sample PAPI workspace, papisamples (y): n
Install sample PAPI workspace, oauth2sample integration (y):? n
Install sample Low-code plugin, mathoperation (y):? ny

config.js updated.
[...]
Copying pjssamples.
Copying sample workspace into C:\profoundjs\modules\oauth2sample
[...]
Profound.js installation complete.

Once you have the oauth2sample workspace installed, then you can follow instructions in the README.md file to learn what changes are necessary to the openapi.json configuration and the sample setup.js.