Difference between revisions of "NATS API Best Practices"
TmmStephen (talk | contribs) |
Tmm vincent (talk | contribs) (cleaning up page before documentation of nats5 changes) |
||
| (One intermediate revision by one other user not shown) | |||
| Line 1: | Line 1: | ||
{{NATS4 Manual | {{NATS4 Manual | ||
| − | | | + | | show_api_admin_section = true |
}} | }} | ||
| − | <pre style="color: red;font-weight: bold;">Please note: This information is best represented on NATS versions higher | + | <pre style="color: red;font-weight: bold;">Please note: This information is best represented on NATS versions higher than 4.1.16.1</pre> |
| − | + | This article lists out several best practices for using the NATS API. These practices are encouraged in order to prevent unwanted access to processes within NATS that would otherwise not be available unless logged in. We encourage you to use the REST API system rather than the SOAP API system, as the SOAP API in NATS is deprecated and included only for backward compatibility. | |
== Restrict Access by IP Address == | == Restrict Access by IP Address == | ||
| − | In | + | In order to use the NATS API, you will need to provide a list of IP addresses will be granted access to the NATS API. In the "Security" section of the [[NATS4 Configuration Admin|Configuration Admin]], this information is stored as a comma separated list of IP addresses set in the "ADMIN_API_ALLOWED_IPS" variable. We recommend that you grant access to only the IP addresses of those who will be actively using the NATS API itself. |
| Line 16: | Line 16: | ||
== API ON/OFF switch == | == API ON/OFF switch == | ||
| − | In addition to allowing | + | In addition to allowing API access to IP addresses, you will need to enable the NATS API itself. In the the "Security" section of the Configuration Admin, turn on the API by checking the box for the "ENABLE_SOAP_API" or "ENABLE_REST_API" settings, depending on which system you plan to use. This configuration is disabled by default, and is available to provide a way for you to quickly turn off both the NATS API to all users should the need arise. We recommend enabling only the API systems you plan to use. |
| − | [[Image:API_PERM_WIKI_SCREEN_04.png|frame|300px|center||||'''In the "Security" section of the Configuration Admin, | + | [[Image:API_PERM_WIKI_SCREEN_04.png|frame|300px|center||||'''In the "Security" section of the Configuration Admin, check the ENABLE_SOAP_API or ENABLE_REST_API settings depending on your use.''']] |
== API Users per System or Server == | == API Users per System or Server == | ||
| − | We recommend | + | We recommend creating separate API accounts for separate uses or servers. This makes it so access to the API systems are limited should that account be compromised. An example of this type of set up would be creating an account for API use in your members area, and creating a separate account for API use on an external Adtool system. If you have members areas on separate servers, it would be best to create a separate account for each server as well. |
[[Image:API_PERM_WIKI_SCREEN_02.png|frame|300px|center||||'''We recommend having separate accounts for specific API purposes.''']] | [[Image:API_PERM_WIKI_SCREEN_02.png|frame|300px|center||||'''We recommend having separate accounts for specific API purposes.''']] | ||
== API Permissions == | == API Permissions == | ||
| − | For each account able to access the API system, we provide the ability to restrict the resources or functions available to them. The permissions system allows you to | + | For each account able to access the API system, we provide the ability to restrict the resources or functions available to them. The permissions system allows you to make available only those systems that an account needs to use. We encourage you to only make available the functions or resources that are necessary to the account itself. For example, if an account is to be used for membership authentication, set the account's API permissions to only allow them access to the member search function. |
=== SOAP API Permissions === | === SOAP API Permissions === | ||
| − | By default, an account has access to all SOAP API functions | + | By default, an account has access to all available SOAP API functions, and you have the ability to disable any functions that are not necessary for the account. Use the check boxes next to each of the functions to select which you wish to make either Enabled or Disabled. Once selected, use the "Disable APIs -->" and "<-- Enable APIs" buttons to move the selected functions from one column to the other. You can also use the "Auto Check:" links to quickly check "All" or "None" of the functions, or "Invert" your selection before Enabling or Disabling functions. |
| Line 36: | Line 36: | ||
=== REST API Permissions === | === REST API Permissions === | ||
| − | By Default, an account does not have | + | By Default, an account does not have access to any of the available REST API resources. Use the check boxes in the "Enabled" column to select which of the collection, method, and resource combinations you would like to Enable for the account. Save the configuration by clicking "Save REST API Permissions" at the bottom of the page. Collections, Methods, or Resources set with '''ANY''' allow the account access to any of the specific option in the combination. For example, Collection/Method/Resource with each option set to '''ANY''' allows the account access to all REST API functions, whereas the Collection of "Adtool" and Method/Resource set to '''ANY''' will give the account access to all functions available only in the "Adtool" collection. |
| − | [[Image:API_PERM_WIKI_SCREEN_05.png|frame|300px|center||||''' | + | [[Image:API_PERM_WIKI_SCREEN_05.png|frame|300px|center||||'''REST API permissions allow you to set available collections/resources/methods per account.''']] |
| Line 46: | Line 46: | ||
=== Membership Authentication API Account === | === Membership Authentication API Account === | ||
| − | This example | + | This is an example configuration for an account to be used for membership authentication through a restricted members area. The image on the left shows the SOAP API permissions for this account with access to only the following functions: get_member_details, record_member_login, and set_member_details. The image on the right shows the account set to the equivalent resources. In this example, this account would be used to authenticate, to record the login to NATS, and to allow the update of member information. |
| − | [[Image:API_PERM_WIKI_SCREEN_06.png|800px | + | [[Image:API_PERM_WIKI_SCREEN_06.png|800px|||||'''SOAP API Member Authentication Account Example''']] |
| − | [[Image:API_PERM_WIKI_SCREEN_07.png|800px | + | [[Image:API_PERM_WIKI_SCREEN_07.png|800px|||||'''REST API Member Authentication Account Example''']] |
| − | === Members | + | === Members Area Across Multiple Servers === |
| − | If you have members areas across multiple servers we recommend | + | If you have members areas across multiple servers, we recommend utilizing a separate API account for each server as shown in this example. |
[[Image:API_PERM_WIKI_SCREEN_08.png]] | [[Image:API_PERM_WIKI_SCREEN_08.png]] | ||
Latest revision as of 22:27, 10 April 2019
Please note: This information is best represented on NATS versions higher than 4.1.16.1
This article lists out several best practices for using the NATS API. These practices are encouraged in order to prevent unwanted access to processes within NATS that would otherwise not be available unless logged in. We encourage you to use the REST API system rather than the SOAP API system, as the SOAP API in NATS is deprecated and included only for backward compatibility.
Restrict Access by IP Address
In order to use the NATS API, you will need to provide a list of IP addresses will be granted access to the NATS API. In the "Security" section of the Configuration Admin, this information is stored as a comma separated list of IP addresses set in the "ADMIN_API_ALLOWED_IPS" variable. We recommend that you grant access to only the IP addresses of those who will be actively using the NATS API itself.
API ON/OFF switch
In addition to allowing API access to IP addresses, you will need to enable the NATS API itself. In the the "Security" section of the Configuration Admin, turn on the API by checking the box for the "ENABLE_SOAP_API" or "ENABLE_REST_API" settings, depending on which system you plan to use. This configuration is disabled by default, and is available to provide a way for you to quickly turn off both the NATS API to all users should the need arise. We recommend enabling only the API systems you plan to use.
API Users per System or Server
We recommend creating separate API accounts for separate uses or servers. This makes it so access to the API systems are limited should that account be compromised. An example of this type of set up would be creating an account for API use in your members area, and creating a separate account for API use on an external Adtool system. If you have members areas on separate servers, it would be best to create a separate account for each server as well.
API Permissions
For each account able to access the API system, we provide the ability to restrict the resources or functions available to them. The permissions system allows you to make available only those systems that an account needs to use. We encourage you to only make available the functions or resources that are necessary to the account itself. For example, if an account is to be used for membership authentication, set the account's API permissions to only allow them access to the member search function.
SOAP API Permissions
By default, an account has access to all available SOAP API functions, and you have the ability to disable any functions that are not necessary for the account. Use the check boxes next to each of the functions to select which you wish to make either Enabled or Disabled. Once selected, use the "Disable APIs -->" and "<-- Enable APIs" buttons to move the selected functions from one column to the other. You can also use the "Auto Check:" links to quickly check "All" or "None" of the functions, or "Invert" your selection before Enabling or Disabling functions.
REST API Permissions
By Default, an account does not have access to any of the available REST API resources. Use the check boxes in the "Enabled" column to select which of the collection, method, and resource combinations you would like to Enable for the account. Save the configuration by clicking "Save REST API Permissions" at the bottom of the page. Collections, Methods, or Resources set with ANY allow the account access to any of the specific option in the combination. For example, Collection/Method/Resource with each option set to ANY allows the account access to all REST API functions, whereas the Collection of "Adtool" and Method/Resource set to ANY will give the account access to all functions available only in the "Adtool" collection.
Examples of API Settings
Membership Authentication API Account
This is an example configuration for an account to be used for membership authentication through a restricted members area. The image on the left shows the SOAP API permissions for this account with access to only the following functions: get_member_details, record_member_login, and set_member_details. The image on the right shows the account set to the equivalent resources. In this example, this account would be used to authenticate, to record the login to NATS, and to allow the update of member information.
Members Area Across Multiple Servers
If you have members areas across multiple servers, we recommend utilizing a separate API account for each server as shown in this example.
