API Security

This document describes the M3 application programming interface (API) authentication and security model. It also gives recommendations on how to configure and set up the environment for access through APIs.

Introduction

An API is an interface to an M3 program that allows an external application program to execute transactions to upload or download specific data, activate certain procedures, etc.

Interaction with M3 API can occur using two different techniques. The traditional way is through a client component running sockets communication in accordance with a proprietary protocol, but now communication through web services has been introduced. The web services allow for HTTP/HTTPS communication and the Rest protocol.

The client component communicates on open channels and is preferably used within an internal network. The Java version of the client interfaces also supports SSL communication and authentication through certificates. Client component communication cannot be used in a multi-tenant Cloud context.

The web services HTTP part likewise communicates on open channels. HTTP is only suitable for internal networks, whereas HTTPS should be used if access is required from external sources. In a multi-tenant cloud context, HTTPS is required.

M3 API implementation

When M3 API technique is used to access M3 software, user credentials must follow the initial log-on.

In all API programs, users are restricted to the companies to which they can have access. Different API programs within different application areas can also have restrictions on the field level and restrictions on facility, warehouse, and so on.

Through M3 API, users may have access to every API program and to every transaction by default, which may not be preferable - but users can be restricted in their use of API programs and their transactions.

M3 BE provides these methods to manage security for M3 API:

  • Authorization by transaction - 'Function. Connect API Authorization' (SES005)
  • Authorization by roles - 'Function. Connect Authorization by Role' (SES400) and 'API Transaction. Connect Security Option' (SES405)

User authentication

M3 users are authenticated through the platform mechanism for user authentication. The user must also be registered in M3 using the program (MNS150).

There are two types of user profiles in relation to M3 API. The type used depends mainly on how the client applications are designed.

  • Users can be working from their workstations with client applications that access the M3 application server directly. They log on as they usually do with their M3 application credentials.
  • Users access the client application from an intermediate server such as a web server and never log on to the M3 application server. Instead, the application logs on using a shared user profile specially created for this purpose. Examples of such an application are M3 WebShop or the M3 API SOAP Server.

M3 users are authenticated by the mechanism for the platform they use. User profiles using M3 API must be defined in the usual way for M3 users.

Shared user profiles used from server applications should, if possible, be defined so that they cannot log on to the application server using interfaces.

Authorization by transaction in (SES005)

It is possible to restrict, down to transaction level, what programs and transactions each user is authorized to use. The program for this purpose is 'Function. Connect API Authorization' (SES005).

System settings in (MNS090)

The API security for authorization by transaction is activated by selecting alternative 1 – 'Security via authorization' for parameter 'API security' in 'System Settings. Open' (MNS090).

When you select alternative 1, users that are authorized to use API transactions must be added in (SES005). If no entries for the user exist in (SES005), the API transaction is considered denied.

Connect authorization in (SES005)

In 'Function. Connect API Authorization' (SES005), add users that need the authority to use M3 API transactions. The default behavior when running in authorization mode is to not allow any API programs or transactions.

Specific program and transactions that are to be allowed for a user can be specified. You can set both program and transactions to prompt to retrieve their values. To simplify entry, all transactions for the current program can be retrieved, and then you can remove the transactions that are not relevant.

Also, it is possible to allow all transactions in a program by specifying the value *ALL for a certain user. Furthermore, a user access to all programs and all transactions can be allowed by specifying *ALL on program level.

Security using authorization by roles for API

The role-based security model utilized for functions can also be used for API transactions where an API program (for example CRS610MI) is equal to a function (for example, 'Customer. Open' (CRS610)). Each API transaction is assigned a security option that is equal to an option for functions. The programs used for this purpose is (SES400) and (SES405).

The security through authorization by roles for API is activated by selecting alternative 2 – 'Security via roles' for parameter 'API security' in 'System Settings. Open' (MNS090).

Note: Before this alternative can be selected, every API transaction and default security option must be generated in (SES405). A transaction that does not exist or with a blank security option in (SES405) is considered restricted and denied for all users.

Security options in (SES405)

Every API transaction must be connected to a security option in 'API Transaction. Connect Security Option' (SES405). Records and security options for all existing API programs and transactions are generated by function key F18='Gen standard' in (SES405). The security options are set to a default value based on the name of the transaction and are equivalent to the standard options (1-6) used in functions. The options can be changed manually later. The program is set up per tenant.

F18 can also be used later to update the program with new API transactions and default security options.

This table shows how the security options are set based on the name of the transaction:

Security option API transaction name begins with
1 Add, Create, Crt
2 Change, Chg Update, Upd
3 Copy, Cpy
4 Delete, Del, Dlt
5 Get, List, Lst, Search, Select, Sel
6 Print, Prt
Note: All transactions where a default security option cannot be identified based on the name are given security option 2.

This table below shows an example of the default security options set for CRS610MI (Customer interface) depending on type of transaction.

Security option API transaction Description
1 Add Create a new customer record
1 AddAddress Create a new customer address
1 AddText Add text for customer
2 CheckPIN Check customer number and pin
2 ChgAddress Modify customer address data
2 ChgBasicData Modify customer basic data
3 Copy Copy an existing customer record
4 Delete Delete a customer record
4 DeleteAddress Delete a customer address record
2 EXPORTSMS Export to SMS
5 GetAddress Retrieve customer address data
5 GetBasicData Retrieve customer basic data
5 LstAddresses List customer address related information

Later, if you want to set up security for a new API program or transaction that has been implemented, you specify the name of the new API program in field 'Program' and press enter. Then, any new transaction for the API is created in table CMNSMI (SES405) with the blank security option. You can either key in the option manually or accept the system default option by using the ‘Default options’ button or function key F14=’Default options’. Only the API transactions with a blank security option are updated with F14.

These are the valid security options for API transactions:

  • Option 00-99 can be set manually.
  • Option 00 does not require any authorization and is considered open for all users.
  • Option '**' is set by function key F14 or F18 in (SES405) and is exempt from security for M3 to run. This security option cannot be changed.
Note: API transactions with a blank security option or not listed in (SES405) are considered restricted and denied for all users if parameter 'API Security'=2-'Security via roles' in (MNS090).

Authorization by role in (SES400)

The security options (1-99) that should be valid for an API program, role, company, and division are defined in 'Function. Connect Authorization by Role' (SES400) in the same way as for functions. For API programs, the related option 11='API transaction security' to open (SES405) can be used. The result of the setup in (SES400) can be viewed in 'Authorization per User. Display' (SES401).

An example of the connection between security option in (SES400) and (SES405) is as follows:

You have created a role called 'DISPLAY' that only should be eligible to transactions that display or list records for an API program. In (SES400) you create a record for the API program and select the check box for security option 5. Then make sure the display and list transactions in (SES405) for the API program are connected to security option 05.

Function in (MNS110)

The parameter 'Auth required' in 'Function. Open' (MNS110) determines if entries are required in (SES401), to allow the user to have access to the API program.

If this parameter should be set to '1', enter the name of the API program in the field 'Function' on the B-panel and select Create. On the E-panel, select 'Function cat'= API – 'API program' and select the check box for 'Auth required' and press enter.

This table shows if a user is authorized to run an API transaction or not depending on the setting of the parameter in (MNS110), set up in (SES401) and (SES405).

Parameter 'Auth required' set to 0:

Record in (SES401) for user/program API transaction in (SES405) and connected security option User authorized to run API transaction
No No Not allowed
No Yes - option blank Not allowed
No Yes - any option 00-99 Allowed
Yes - option 5 allowed No Not allowed
Yes - option 5 allowed Yes - option blank Not allowed
Yes - option 5 allowed Yes - option 02 Not allowed
Yes - option 5 allowed Yes - option 05 Allowed

Parameter 'Auth required' set to 1:

Record in (SES401) for user/program API transaction in (SES405) and connected security option User authorized to run API transaction
No No Not allowed
No Yes - option blank Not allowed
No Yes - option 05 Not allowed
Yes - option 5 allowed No Not allowed
Yes - option 5 allowed Yes - option blank Not allowed
Yes - option 5 allowed Yes - option 02 Not allowed
Yes - option 5 allowed Yes - option 05 Allowed