Authentication - Authorization

There are 4 parts to controlling who can call your APIs:

Configure which types of Authentication to enable.
1. Authentication is a way to prove the caller is who they say they are, such as user/password
Configure which type of Authorization to enable.
1. Authorization is a way to further refine which authenticated callers are allowed or denied for specific APIs
Configure API Users
Configure security permissions on each API.

If you need to handle other means of Authentication than below supported options, you can setup a Custom Authentication module. See here to do this.

Using this Custom Authentication option can be done instead of the above Items 1, 2 and 3.
This Custom Authentication can integrate into above Item 4, or can override it.

** The default configuration is such that any callers can run API.

Authentication Setup

Navigate to the Profound.js IDE
On the Home Ribbon, Click API Options and choose OpenAPI Configuration

This will open a new designer tab where you can configure several options, such as your API Explorer title bar information and API Security configuration.

To learn more about OpenAPI, see their documentation page for version 3.0.3.

We are concerned with the following 3 sections of this json file:

The "x-allowAnonymous" property. Set this property to true to enable anybody to call your APIs.
The "security" section. This section is where you define what security schema are to be checked when an API is called.
- These securities are applied to all APIs however a specific API route can override these securities.
- Advanced: Notice that this section is an array of objects. It does allow for configuring multiple schemas within each array element
- See here for even more information.

{name}

[]

Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object. The array MUST be empty.

The "components" / "securitySchemes" section. This section is where you define the different types of credentials.
- See here for event more information.

Field Name	Type	Applies To	Description

Field Name	Type	Applies To	Description
type	`string`	Any	REQUIRED. The type of the security scheme. Valid values are `"apiKey" or "http"`.
description	`string`	Any	A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
name	`string`	`apiKey`	REQUIRED. The name of the header, query or cookie parameter to be used.
in	`string`	`apiKey`	REQUIRED. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
scheme	`string`	`http`	REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
x-ibmi	`boolean`	`http`	Set this property to true if this security scheme is for IBMi user/password credentials.

This configuration is case-sensitive and must be a valid JSON document.

Below is a simple example of a single security using a single scheme. This example is using API Key Authentication.

The "name" of the security scheme can be anything, below the name this one "MyAPIKey".
Notice that "MyAPIKey" is defined as an "apiKey" type, and requires a property named "X-API-KEY" in the header.
Also, to enable this scheme authentication, it must be included in the "security" section and the name must exactly match.

With the below configuration, this means when an API is called the caller must send a header with a property called "X-API-KEY".

The API Framework will attempt to authenticate to a single user with that "X-API-KEY" value.

An example of a configuration that secures all APIs to require an API key credentials

{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "1.0.0"
  },
  "components": {
    "securitySchemes": {
      "MyAPIKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "x-allowAnonymous": false,
  "security": [
    {
      "MyAPIKey": []
    }
  ]
}

Below is another simple example of a single security using a single scheme. This example is using User/Password Authentication.

The "name" of the security scheme can be anything, below the name this one "User".
Notice that "User" is defined as a "http" type with scheme basic. This means it requires the caller to send an encoded basic User/Password value for "Authorization" in the header.
Also, to enable this scheme authentication, it must be included in the "security" section and the name must exactly match.

With the below configuration, this means that when an API is called the caller must include a header with a property called "Authorization" that contains a standard encoding of basic user:password.

The API Framework will then attempt authenticate to a single user profile that matches the encoded credentials.

An example of a configuration that secures all APIs to require User/Password credentials

{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "2.1.6"
  },
  "components": {
    "securitySchemes": {
      "User": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "x-allowAnonymous": false,
  "security": [
    {
      "User": []
    }
  ]
}

Below is another simple example of a single security using a single scheme. This example is using IBMi User/Password Authentication.

An example of a configuration that secures all APIs to require IBM i User/Password credentials

{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "2.1.6"
  },
  "components": {
    "securitySchemes": {
      "IBMiUser": {
        "type": "http",
        "scheme": "basic",
        "x-ibmi": true
      }
    }
  },
  "x-allowAnonymous": false,
  "security": [
    {
      "IBMiUser": []
    }
  ]
}

Below is an example that shows how you can use multiple schemes.

In the "security" section, there is still a single array element, however there it has two properties: "AppKey" and "ClientID"

With the below configuration, this means when an API is called the caller must send a header with a property called "AppKey" and another property called "ClientID".

The API Framework will attempt to authenticate to a single user with both the "AppKey" and "ClientID" values.

An example of a configuration that secures all APIs to require two API credentials

For advanced requirements

Below is an example of how you can combine different schema along with different securities.

In the "security" section, there are now three array elements.

With the below configuration, this means when an API is called the caller must send one of the below combinations:

For the "User" security:
- A Header with property name "Authorization" with a basic encoded user:password
For the "APIKey" and "AuthToken":
- A Header with property name "X-API-KEY" and cookie with a name of AuthToken
For the "AppKey" and "ClientID":
- A Header with a property called "AppKey" and another property called "ClientID"

The API Framework will go through each of these array elements and attempt to authenticate to a single user with those matching credentials.

A more advanced configuration

Authorization Setup

Navigate to the Profound.js IDE
Choose the type of API Security you need:
1. Simple User Authentication - A way to prove the caller is who they say they are, such as user/password
2. Role Based Authorization - A way to further refine which authenticated callers are allowed or denied for specific APIs
  1. This is the most common choice.
  2. You can upgrade to this level at any time
To enable Role Based Authorization, you must configure the Security Security Store one time.
1. On the Home Ribbon, Click API Options and choose Security Store Configuration

Select the Database connection and, if required, the database schema.
This will create, as needed, the Security Store as well as convert any or the simple User Authentication records.

API users

On the Home Ribbon, Click API Options and choose User Authentication, then API Users

From here you can add, remove, and change users and their credentials.

Simple User Authentication

Role Based Authorization

Below is the screen that is presented when adding or editing users.
** Based on configuration, a User may require multiple identities for uniquely identify them.

** Notice under the Add button, there are additional options to add other types of identification.

Simple User Authentication

Role Based Authorization

On the Roles tab is where you assign the different role(s) for this user.