|
|
| (18 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | {{DISPLAYTITLE:i2Rest Advanced Setup}}
| + | This section describes configuration options of i2Rest Server. [[I2Rest_quick_config|Basic configuration]] allows only demo server functionality, and must be extended to supply full functional server instancence. Combining examples bellow you can achieve server functionality that suits your requirements. <br> |
| − | ''Паша, я думал что не так с этим документом. Мне кажется он слишком сумбурный и тяжелый. Переспал с этой мыслью :) Предлагаю такой порядок изложения:''<br/>
| |
| − | "На данной странице приведены различные варианты настройки сервера, позволяющие достить тех или иных результатов. Вы можете комбинировать данные примеры для того чтобы получить конфигурацию, которая удовлетворят вашим требованиям."<br/>
| |
| − | ''Дальше делаем список ссылок на страницы, в которых приводим примеры различных кейсов, у тебя я так понял уже большая коллекция :)''<br/>
| |
| − | * Защита соединений при помощи https
| |
| − | * Использование file: ендпойнт
| |
| − | * How to require OAuth2 authentication (тут только *LOCAL сессии и минимальную настройку юзера, клиента и скоупа для run_program, pcml для echo)
| |
| − | * How to allow command call API (тут только *LOCAL сессии и минимальную настройку юзера, клиента и скоупа для run_command)
| |
| − | * How to allow calls to management API
| |
| − | * How to call API located on remote IBM i server
| |
| − | * Custom scopes. Пока тут можно рассказать про то что можно добавить собственный скоуп, использовать его в настройке полномочий и передавать его в сессию
| |
| − | * Примеры настройки различных API - ссылка на страницу на которой будет список ссылок на страницы с различными примерами PCML (библиотека примеров настроек PCML)
| |
| | | | |
| − | ''Каждый раздел описывается на отдельной странице, аналогично тому как описан basic сценарий. То есть - в начале пишем что в этом сценарии отражено, описываем предварительные действия и приводим целиком все связанные со сценарием настройки (json и pcml), красным выделяем места которые нужно поменять под себя. Json должен быть таким, чтобы в нем были очевидны те минимальные отличия от basic, которые нужны для того чтобы решить требуемую задачу. Возможно эти отличия получится выделить цветом. В конце можно привести ссылки на основные точки в reference, которые важны для этого кейса''
| + | * [[Using secured connections]] |
| − | | + | * [[i2Rest Gate URL definition using Unix socket|Serving incoming connections using Unix sockets]] |
| − | ''Мне кажется так документ приобретет чистую структуру, не будет перегружен, и в то же время его можно будет легко расширять''
| + | * [[I2Rest_with_syslog|Using syslog with i2Rest Server]] |
| − | | + | * [[Configuring OAuth2 authorization]] |
| − | | + | * [[Run_command_Api_config|How to allow calls to run_command API]] |
| − |
| + | * [[Management_API_config|How to allow calls to management API]] |
| − | This section describes configuration options of i2Rest Server. [[I2Rest_quick_config|Basic configuration]] allows only demo server functionaliy, and must be extended to supply full functional server instancence.<br>
| + | * [[Remote_API_call_config|How to call API located on remote IBM i server]] |
| − | ==Some words about basic configuration==
| + | * [[I2Rest_Basic_PowerApps_Connector|How to create Microsoft Power Apps custom adapter to i2Rest Server]] |
| − | Should start with important explanations about the basic configuration (shown bellow in snippets for your convenience).
| + | i2Rest server should be [[I2Rest_Start|restarted]] to aplly your new configuration *.json. |
| − | === i2Rest Gates===
| |
| − | <pre>
| |
| − | ...
| |
| − | "gates":
| |
| − | {
| |
| − | "main" : {"url":"http://<host_name>[:port] (for example api.i2rest.com:1234)"},
| |
| − | "management" : {"url":"http://<host_name>[:port] (for example api.i2rest.com:4321)"}
| |
| − | },
| |
| − | ...
| |
| − | </pre>
| |
| − | [[I2Rest_Gates#i2Rest_Gates|i2Rest Gate]] is the endpoint where the server listens for incoming requests. The server uses up to three endpoints to process requests from clients, administrators/managers and sessions. Configuration file can contain up to three gate objects to setup these endpoints. If the configuration does not contain a setting for some gate, then the default setting is used - <code>file:</code> protocol at temporary location.<br/> | |
| − | Detailed description of all available configuration options for gates is [[Gates_object|here]]
| |
| − | ==== http ====
| |
| − | This is a common protocol, without encryption. You can use this protocol in a fully secure network environment. Example:
| |
| − | "gates":
| |
| − | {
| |
| − | ...
| |
| − | "main": {"url":"<nowiki>http://192.168.1.123:5678</nowiki>", ...},
| |
| − | ...
| |
| − | },
| |
| − | ==== https ====
| |
| − | To protect the connections, use the https protocol. i2Rest Server uses standard [https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/apis/unix9a.htm IBM i GSK API] to protect connections. All required parameters are configured using DCM, see [[I2Rest_secured_gate|detailed guide]]. Example:
| |
| − | "gates":
| |
| − | {
| |
| − | ...
| |
| − | "main": {"url":"<nowiki>https://192.168.1.123:5678</nowiki>", "dcm_server_id":"MYSERVER", ...},
| |
| − | ...
| |
| − | },
| |
| − | ==== file ====
| |
| − | When your i2Rest Server instance and its clients both located on the same IBM i server, it is reasonable to use <code>file:</code> protocol. For example, you can use this protocol for management gate, to perform management functions using local i2Rest Client. i2Rest Server is able to listen incoming requests at some [https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzab6/uafunix.htm%7Cunix unix socket] defined as a file at IFS. In this case, the server will not be accessible externally. i2Rest Server uses temporary <code>file:</code> endpoints when it can't find configuration for some gate. Temporary <code>file:</code> endpoints are created at <code>/tmp</code> folder, for example <code>/tmp/AS5WRD7DCJ</code>. Example:
| |
| − | | |
| − | "gates":
| |
| − | {
| |
| − | ...
| |
| − | "session": {"url":"file:///tmp/session_gate", ...},
| |
| − | ...
| |
| − | },
| |
| − | === i2Rest session system===
| |
| − | <pre>
| |
| − | ...
| |
| − | "session_systems":
| |
| − | [
| |
| − | { "name" : "*ANONYMOUS",
| |
| − | "submit" : "SBMJOB JOB(I2RESTA) \
| |
| − | USER(${user}) \
| |
| − | CMD(CALL I2REST \
| |
| − | PARM('-session' \
| |
| − | '-url' '${surl}' \
| |
| − | '-uid' '${uid}' \
| |
| − | '-user' '${user}')) \
| |
| − | INLLIBL(I2REST)"
| |
| − | }
| |
| − | ],
| |
| − | ...
| |
| − | </pre>
| |
| − | Session system is about submitting IBM i jobs that should process incoming requests. In our case [[I2Rest_anonymous_sessions]]
| |
| − | === i2Rest PCML===
| |
| − | "pcmls":
| |
| − | [
| |
| − | {
| |
| − | "pcml_mount" : "echo",
| |
| − | "pcml_file" : "<complete name of i2restecho.pcml on IFS (for example /tmp/PCML/i2restecho.pcml)>",
| |
| − | "valid_in_anonymous" : true
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | pcmls object is about [[I2Rest_API_Implementation]] [[I2Rest_PCML_syntax#openapi30_tag]]
| |
| − | | |
| − | =SSL=
| |
| − | The first thing we recommend to add to the [[I2Rest_quick_config|basic server configuration]] is a https protocol connections protection. Please follow [[I2Rest_secured_gate|ssl guide]].
| |
| − | | |
| − | =Request authorization=
| |
| − | Most of requests to i2Rest Sever require authorization. Such requests as [[I2Rest_API#run_command_API|IBM i command call]], [[I2Rest_API#run_program_API|API call]] (except anonymous API call) and [[I2Rest_API#Management_APIs|management api call]] will not be served without OAuth2 token with appropriate [[I2Rest_scopes|scope]]. There is a [[OAuth2_object|OAuth2 object]], representing built-in authorization model. [[OAuth2_object#Settings_for_built-in_implementation|i2Rest built-in authorization model]] configuration options on example.<br>
| |
| − | <div id="Oauth2_obj_template">
| |
| − | "OAuth2":
| |
| − | {
| |
| − | "scopes": {"management_functions" : {"description":"i2Rest management APIs call"},
| |
| − | "run_program" : {"description":"Run *PGM and *SRVPGM"},
| |
| − | "run_command" : {"description":"Run CL command"}
| |
| − | },
| |
| − | "users":
| |
| − | {
| |
| − | "<span style="color:red;">USRX</span>":{"description":"<span style="color:red;">John Johnes</span>","valid_clients":{"<span style="color:red;">TSTCLNT</span>":{"scopes":["management_functions"]}}}
| |
| − | },
| |
| − | "clients":
| |
| − | {
| |
| − | "<span style="color:red;">TSTCLNT</span>":{"redirect_uri":"<span style="color:red;"><main gate URL></span>/oauth2/redirect",
| |
| − | "description":"Test client",
| |
| − | "valid_scopes":["management_functions"],
| |
| − | "valid_grant_types":["authorization_code"]}
| |
| − | },
| |
| − | "tokens": {"type":"token"},"codes":{"type":"code"}
| |
| − | }
| |
| − | <div>
| |
| − | The snippet above shows us In general worlds i2Rest authorization model is something like '''WHAT''' is allowed and to '''WHOM''', and '''HOW''' it realized. '''WHAT''' parameters - are the "scopes", '''HOW''' parameters - "tokens", '''WHOM''' parameters - "users" and "clients" (built-in authorization model implies that both "users" and "clients" has to be registered as an IBM i users). So we can see that user '''USRX''' using client '''TSTCLNT''' is allowed to do some actions within '''"managment_functions"''' scope. And these are exactly the settings of Oauth2 object that we need to perform a Мanagement api call.<br>
| |
| − | | |
| − | ==Мanagement API call==
| |
| − | So, what you have to do before we can test Мanagement API call to i2Rest Server:
| |
| − | :a) Register two users on IBM i - one for a "сlient" parameter and one for a "user" parameter.
| |
| − | :b) Fill the [[I2Rest_Advanced_Setup#Oauth2_obj_template|OAuth2 object template]] above with IBM i users values. Then add the snippet to your [[I2Rest_quick_config|basic server configuration]](with or without ssl protection) and put your new *.json anywhere on IBM i IFS.
| |
| − | :c) Restart server to apply your new configuration *.json.
| |
| − | Now let's test the configuration obtaining [[Auth_profile_SoapUI|Oauth2 token with SoapUI]], and than proceed to [[Manage_API_SoapUI|Management api authorized call]].
| |
| − | | |
| − | == run_program API call==
| |
| − | Unlike anonimous API call we performed in our [[I2Rest_Server#basic_guide|basic guide]], authorized API call requires Oauth2 token with [[I2Rest_scopes#run_program|"run_program" scope]] and <code>*local</code> [[I2Rest_Gates#Session_System|Session System]] defined.
| |
| − | So that's how we will change your [[I2Rest_quick_config|basic server configuration]] (with or without ssl protection) to perform authorized run_program API call:
| |
| − | :a) Add the snippet bellow to the [[Session_system_object|session systems object]]:
| |
| − | <pre>{
| |
| − | "name": "*LOCAL",
| |
| − | "submit": SBMJOB JOB(I2RESTS) USER(${user})
| |
| − | CMD(CALL I2REST PARM(
| |
| − | '-session'
| |
| − | '-url' '${surl}'
| |
| − | '-uid' '${uid}'
| |
| − | '-user' '${user}'
| |
| − | '-init' 'ADDLIBLE I2REST'))
| |
| − | '-dcm_client_id' 'MYCLIENT'))"
| |
| − | },
| |
| − | </pre>
| |
| − | :b) Register two users on IBM i - one for a "сlient" parameter and one for a "user" parameter.
| |
| − | :c) Fill the [[I2Rest_Advanced_Setup#Oauth2_obj_template|OAuth2 object template]] above with IBM i users values and add to your *.json.
| |
| − | :d) Add the "run_program" scope to scopes object.
| |
| − | :e) Change the pscms object as follows:
| |
| − | "pcmls":
| |
| − | [
| |
| − | {
| |
| − | "pcml_mount" : "echo",
| |
| − | "pcml_file" : "<complete name of i2restecho.pcml on IFS (for example /tmp/PCML/i2restecho.pcml)>",
| |
| − | "valid_in_anonymous" : <span style="color:red;">false</span>
| |
| − | }
| |
| − | ]
| |
| − | :f) Restart server to apply your new configuration *.json.
| |
| − | Now you can update your [[I2Rest_Basic_Test#SOAP_UI|SoapUI ECHO test project]] with [[Auth_profile_SoapUI|Authorization profile]] and perform your authorized API call.
| |
