API Server configuration commands

Configuring the API Server can include configuring its policy, session management, transaction confirmation management, external authentication and external identity provider plugins. The session management plugin contains several additional plugins. Each plugin is controlled by a set of parameters contained in a JSON configuration object. The commands listed in this section enable you to import configuration objects from files, export configuration objects to files, create configuration objects, and delete configuration objects. Configuration is tenant specific.

You can control what information is returned from the Nok Nok Server to your client app, update the trusted list of origins to include your Web client, change the default FIDO policies for FIDO operations, configure session management, and configure transaction confirmation management.

All the commands in this section have type and name attributes. type usually corresponds to a plugin and name to a configuration object for that plugin. The table below shows the configuration objects for each plugin.

Table of Plugins and Their Configuration Objects

You can generate the jwt_config, credsim_config, and jws_config objects for many of these using the apiserver create command. To create the other configuration objects, see API Server Configuration.

Import

Syntax

./nnl-mgmt.sh apiserver import [-tenantid <tenantid> -type <objectType> -name <objectName>] -file <configurationFilePath> [-overwrite <yes|no>]

Description

Imports API Server configuration files into the database. You can either import a single configuration or a ZIP file.

• Single configuration file: You must provide the tenantid, type, and name parameters. The command fails if you don't provide the tenantid in this mode. The content of the configuration file depends on the configuration object type (type), either the API Server itself or one of its plugins. For details about these configuration objects and their fields, refer to API Server Configuration.

An example of a file containing the API Server's Main object is shown below. A developer wants the API Server to return more information to their app. By default, the API Server returns all device information, the handle (unique ID) for any registered authenticators returned in the result, and a hint about how the authenticator communicates with the client (this is required to handle FIDO2). It filters out the remaining data. The developer wants the API Server to return the following additional information which requires modifying the Main object.

• The FIDO policy name used for registration/authentication

• The oobRefID scanned by the second device during an OOB FIDO registration or authentication (if the QR code or push notification contained an oobRefID)

• For each authenticator used during an operation:

  • AAID

  • Version

• The transaction ID, if a transaction was performed

{
    "mfas_response_filter":{
        "additionalInfo":{
            "policyName":true,
            "oobRefID":true,
            "authenticatorsResult":[
                {
                    "aaid":true,
                    "authenticatorVersion":true,
                    "handle":true,
                    "attachmentHints":true
                }
            ],
            "device":true,
            "transaction":true
        }
    }
}

If the file is called Main.json, the following command uploads the configuration object to the default tenant.

./nnl-mgmt.sh apiserver import -tenant default -type Main -name Main ‑file Main.json

• ZIP file: Only specify file. The tenantid, type, and name are ignored if provided. The ZIP file must have the following folder structure.

• The root folder name must be the tenant ID.

• A folder name under the root folder must be an object type. Valid object types are Main, PolicyPlugin, SessionPlugin, TransactionPlugin, ExternalIdentityProvider, or ExternalAuthenticationPlugin.

• Each folder contains one or more JSON configuration files. A file's base name, like jwt_config for jwt_config.json, corresponds to a possible value for the name parameter.

For example:

default
 ├─── SessionPlugin
 │      ├─── Main.json
 │      ├─── credsim_config.json
 │      ├─── ip_address_plugin.json
 │      ├─── jws_config.json
 │      ├─── jwt_config.json
 │      └─── ua_parser.json
 │
 └─── PolicyPlugin
        ├─── Main.json
        └─── default_config.json

By default, the ZIP file size must be less than 512KB. Change the maximum ZIP file size by setting the nnl.api.server.config.file.size.kb property for the Admin tenant. For example, to increase the maximum ZIP file size to 1MB:

./nnl-mgmt.sh properties set -name nnl.api.server.config.file.size.kb -value 1024 ‑tenantid Admin

Example

./nnl-mgmt.sh apiserver import -file cfg.zip

Sample result:

Successfully imported configurations from 'cfg.zip'.

Export

Syntax

./nnl-mgmt.sh apiserver export [-tenantid <tenantid>] [-type <objectType>] [-name <objectName>] -file <configurationFilePath>

Description

Exports API Server configuration objects from the database into a file. Values for tenantid, type, and name are treated like filters for the configuration information you want exported.

For example, if you only specify the tenantid, then all configuration objects for that tenant ID are exported into a ZIP file. Specifying a tenantid of investment and type of SessionPlugin results in exporting all session plugin-related configuration for the investment tenant. Export a single configuration object by specifying tenantid, type, and name.

A custom plugin has a different object type from those used by Nok Nok plugins.

Examples

./nnl-mgmt.sh apiserver export -tenantid default -type SessionPlugin -file test.zip

Sample result:

Successfully exported configurations into a ZIP archive at 'test.zip'.

The example below exports the configuration object for the User Agent Parser plugin into the file ua_parser.json.

./nnl-mgmt.sh apiserver export -tenantid default -type SessionPlugin -name ua_parser -file ua_parser.json

Create

Syntax

./nnl-mgmt.sh apiserver create [-tenantid <tenantid>] -type <objectType> ‑name <objectName> [-issuer <jwtIssuerURL>]

Description

The apiserver create command enables you to easily create JWT configuration objects for the plugins listed below. Use the values listed in the Type and Configuration Object columns for the type and name parameter, respectively.

The links below take you to examples that describe the jwt_config and jws_config objects that this command creates.

• Create a jwt_config object for the JWT Processor plugin

• Create a jwt_config object for the External Authentication plugin

• Create a jws_config object for the EMV 3DS Generator plugin

• Create a jwt_config object for the Transaction plugin

You can modify these configuration objects to change the algorithm, key, key location, add issuers, and so on. To do that you export the configuration object into a file (see the apiserver export command), edit the file to make your changes, and import the file (see the apiserver import command).

For detailed instructions on common changes to make to jwt_config, see When to Modify a JWT Configuration Object. These instructions can also be applied to jws_config and access_id_jwt_config because these objects share many of the same fields with jwt_config.

Examples

Example 1: Create a jwt_config object for the JWT Processor plugin

This command creates a jwt_config object for the JWT Processor plugin for the finance tenant. The issuer is the API Server. The JWT Processor plugin uses this object to generate JWTs as well as validate JWTs that it receives.

./nnl-mgmt.sh apiserver create -tenantid finance -type SessionPlugin -name jwt_config -issuer "https://myAPIServer.com"

The resulting jwt_config object is shown below. apiserver create assigns the issuer and tenant to the issuer and audiences fields, respectively, in both the generate and validate objects. It also generates a new secret key. These fields are highlighted.

Using this new jwt_config, the JWT Processor plugin generates and validates signed JWTs using the symmetric HS256 algorithm. The lifespan of generated JWTs is 1 hour.

{
  "generate": {
    "issuer": "https://myAPIServer.com",
    "audiences": [
      "finance"
    ],
    "nbf_delta": 0,
    "encryption": "",
    "token_lifetime": 3600,
    "kid": "hs256_key",
    "algorithm": "HS256",
    "jwks_uri": "",
    "jwks_object": {
      "keys": [
        {
          "kty": "oct",
          "use": "sig",
          "kid": "hs256_key",
          "k": "AMCjsKw-rUOyeNawc9LS6kDNhvmdEboFqazM_14FuNE"
        }
      ]
    }
  },
  "validate": {
    "issuers": [
      {
        "issuer": "https://myAPIServer.com",
        "audiences": [
          "finance"
        ],
        "encryption": "",
        "token_lifetime": 3600,
        "max_clock_skew": 180,
        "algorithm": "HS256",
        "jwks_object": {
          "keys": [
            {
              "kty": "oct",
              "use": "sig",
              "kid": "hs256_key",
              "k": "AMCjsKw-rUOyeNawc9LS6kDNhvmdEboFqazM_14FuNE"
            }
          ]
        }
      }
    ]
  }
}

Example 2: Create a jwt_config object for the External Authentication plugin

This command specifies that the issuer is the RP Server (https://MyRPServer.com) that performs the external authentication method instead of the API Server. This applies to the marketing tenant.

./nnl-mgmt.sh apiserver create -tenantid marketing -type ExternalAuthenticationPlugin -name jwt_config -issuer "https://MyRPServer.com"

The resulting jwt_config object is shown below. apiserver create assigns the issuer and tenant to the issuer and audiences fields, respectively. It also generates a new secret key. These fields are highlighted. The External Authentication plugin only validates JWTs issued by the RP Server so it only uses the validate object in jwt_config.

The new jwt_config validates signed JWTs sent from the RP Server using the symmetric HS256 algorithm. The lifetime of any incoming JWT is 3 minutes. For more information about External Authentication Methods, see External authentication.

{
  "generate": {
    "issuer": "https://MyRPServer.com",
    "audiences": [
      "marketing"
    ],
    "nbf_delta": 0,
    "encryption": "",
    "token_lifetime": 180,
    "kid": "hs256_key",
    "algorithm": "HS256",
    "jwks_uri": "",
    "jwks_object": {
      "keys": [
        {
          "kty": "oct",
          "use": "sig",
          "kid": "hs256_key",
          "k": "lOszKnlUdMu2wj5-jj8oDxE8kzEsehqhrA6fsfNNCoI"
        }
      ]
    }
  },
  "validate": {
    "issuers": [
      {
        "issuer": "https://MyRPServer.com",
        "audiences": [
          "marketing"
        ],
        "encryption": "",
        "token_lifetime": 180,
        "max_clock_skew": 9,
        "algorithm": "HS256",
        "jwks_object": {
          "keys": [
            {
              "kty": "oct",
              "use": "sig",
              "kid": "hs256_key",
              "k": "lOszKnlUdMu2wj5-jj8oDxE8kzEsehqhrA6fsfNNCoI"
            }
          ]
        }
      }
    ]
  }
}

Example 3: Create a jws_config object for the EMV 3DS Generator plugin

The command below creates a new jws_config object for the EMV 3DS Generator plugin. This plugin creates a JWS with EMV 3DS data that the API Server issues. Consequently, a jws_config object only has a generate object.

./nnl-mgmt.sh apiserver create -tenantid finance -type SessionPlugin -name jws_config

The resulting jws_config is shown below, the highlighted field is the new secret key.

{
  "generate": {
    "kid": "hs256_key",
    "algorithm": "HS256",
    "jwks_uri": "",
    "jwks_object": {
      "keys": [
        {
          "kty": "oct",
          "use": "sig",
          "kid": "hs256_key",
          "k": "xPDDxnzzcbeep0LptFPYlXNeeeBtmkXmSbUQOmzbKLQ"
        }
      ]
    }
  }
}

Example 4: Create a jwt_config object for the Transaction plugin

The command below generates a new jwt_config object for the Transaction plugin for a tenant called Marketing.

./nnl-mgmt.sh apiserver create -tenantid Marketing -type TransactionPlugin -name jwt_config -issuer "https://MyAPIServer.com"

Delete

Syntax

./nnl-mgmt.sh apiserver delete [-tenantid <tenantid>] -type <objectType> ‑name <objectName>

Description

Deletes the specified API Server configuration objects from the database.

Example

./nnl-mgmt.sh apiserver delete -type ALL -name Main

Sample result:

Successfully deleted the configuration(s).

List

Syntax

./nnl-mgmt.sh apiserver list [-tenantid <tenantid>]

Description

This command lists all configuration objects that exist for the API Server and its enabled plugins for a given tenant.

Examples

The example below lists configuration objects for the default tenant. Since the API Server and its plugins can use the same name for a configuration object, the table includes the object type.

./nnl-mgmt.sh apiserver list

Sample result:

Listing API Server configurations
+==========+==============================+===================+
| TenantID | ObjectType                   | ObjectName        |
+==========+==============================+===================+
| default  | ExternalAuthenticationPlugin | Main              |
| default  | ExternalAuthenticationPlugin | jwt_config        |
| default  | Main                         | Main              |
| default  | PolicyPlugin                 | Main              |
| default  | PolicyPlugin                 | default_config    |
| default  | SessionPlugin                | Main              |
| default  | SessionPlugin                | ip_address_plugin |
| default  | SessionPlugin                | jws_config        |
| default  | SessionPlugin                | jwt_config        |
| default  | SessionPlugin                | ua_parser         |
| default  | TransactionPlugin            | Main              |
| default  | TransactionPlugin            | jwt_config        |
+==========+==============================+===================+