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).
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 |
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.
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 |