|
|
(77 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> |
− | Let's proceed updating i2Rest Server configuration on the way to full functional server instance.<br>
| |
− | =SSL=
| |
− | The first thing we recommend to add to a [[I2Rest_quick_config|basic server configuration]] is a https protocol connections protection. Please follow [[I2Rest_secured_gate|detailed guide]].
| |
− | =Request authorization=
| |
− | Most of requests to i2Rest Sever instance 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|Мanagement api call]] require Oauth2 token with appropriate scope to be served. Let's observe i2Rest built-in authorization model configuration options.<br>
| |
| | | |
− | ==Мanagement api call==
| + | * [[Using secured connections]] |
− | Look at the simple template bellow (its actually a complete config to perform a Мanagement api call) :
| + | * [[i2Rest Gate URL definition using Unix socket|Serving incoming connections using Unix sockets]] |
− | <pre>
| + | * [[I2Rest_with_syslog|Using syslog with i2Rest Server]] |
− | {
| + | * [[Configuring OAuth2 authorization]] |
− | "curdir" : "/i2rest/1.0.0",
| + | * [[Run_command_Api_config|How to allow calls to run_command API]] |
− | "debug" : 7, "syslog":"udp://localhost:514",
| + | * [[Management_API_config|How to allow calls to management API]] |
− | "gates":
| + | * [[Remote_API_call_config|How to call API located on remote IBM i server]] |
− | {
| + | * [[I2Rest_Basic_PowerApps_Connector|How to create Microsoft Power Apps custom adapter to i2Rest Server]] |
− | "main" : {"url":"https://api.i2rest.com:22088","dcm_server_id":"MYSERVER"},
| + | i2Rest server should be [[I2Rest_Start|restarted]] to aplly your new configuration *.json. |
− | "management" : {"url":"https://192.168.0.233:8080","dcm_server_id":"MYSERVER"}
| |
− | },
| |
− | "session_systems":
| |
− | [
| |
− | {
| |
− | "name" : "*ANONYMOUS",
| |
− | "submit" : "SBMJOB JOB(I2RESTA) USER(${user})
| |
− | CMD(CALL I2REST PARM('-session' '-url' '${surl}' '-uid' '${uid}' '-user' '${user}')) INLLIBL(I2REST)"
| |
− | }
| |
− | ],
| |
− | "pcmls":
| |
− | [
| |
− | {
| |
− | "pcml_mount" : "echo",
| |
− | "pcml_file" : "/home/btpl/jpcml/i2restecho.pcml",
| |
− | "valid_in_anonymous" : true
| |
− | }
| |
− | ],
| |
− |
| |
− | "OAuth2":
| |
− | {
| |
− | "scopes": {"management_functions" : {"description":"Invoke i2Rest manager APIs"}},
| |
− | "users":
| |
− | {
| |
− | "BTPL":{"description":"Pavel Lobko", "valid_clients":{"OAUTH21":{"scopes":["management_functions"]}}}
| |
− | },
| |
− | "clients":
| |
− | {
| |
− | "OAUTH21":{"redirect_uri":"https://api.i2rest.com:22088/oauth2/redirect",
| |
− | "description":"Test client",
| |
− | "valid_scopes":["management_functions"],
| |
− | "valid_grant_types":["authorization_code","client_credentials"]}
| |
− | },
| |
− | "tokens": {"type":"token"},"codes":{"type":"code"}
| |
− | }
| |
− | }
| |
− | </pre>
| |
− | We have something new here - [[OAuth2_object|Oauth2 object]], representing built-in authorization model. In general worlds i2Rest authorization model is something like WHAT is allowed and to WHOM, and HOW it realized. So WHAT allowed parameters - are the "scopes", HOW parameters - "tokens", WHOM parameters - "users" and "clients". Please note, that built-in authorization model implies that both "users" and "clients" has to be registered as an IBM i users.<br>
| |
− | So, what you have to do before we can test authorized call to i2Rest Server instance:
| |
− | :a) Register two users on IBM i - one for a "сlient" parameter and one for a "user" parameter.
| |
− | :b) Fill the template above with IBM i users values and save template as *.json anywhere on IBM i IFS.
| |
− | :c) Restart sever to apply your new configuration *.json.
| |
− | Now let's test the configuration obtaining [[Auth_profile_SoapUI|Oauth2 token with Soap UI]], and than proceed to [[Manage_API_SoapUI|Managment api authorized call]].
| |
− | | |
− | == RUN_PROGRAM Api call==
| |
− | ----
| |
− | This section describes the advanced configuration options of i2Rest Server. To configure, the file in the JSON format is used, the settings reference is [[I2Rest_Config|here]]
| |
− | __TOC__
| |
− | | |
− | = i2Rest Gates =
| |
− | [[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]]
| |
− | == i2Rest Gates protocols ==
| |
− | === 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 Sessions =
| |
− | Ссылка или дублирование "что такое session system".<br/>
| |
− | Ссылка на reference настройки<br/>
| |
− | Упомянуть о сессиях на другой IBM i и на другой платформе<br/>
| |
− | Привести примеры настройки сессий<br/>
| |
− | * Обычные сессии (*LOCAL)
| |
− | <pre>
| |
− | {
| |
− | "name": "*LOCAL",
| |
− | "submit":"SBMJOB JOB(I2RESTS) USER(${user}) \
| |
− | CMD(CALL I2REST/I2REST PARM( \
| |
− | '-session' \
| |
− | '-url' '${surl}' \
| |
− | '-uid' '${uid}' \
| |
− | '-user' '${user}' \
| |
− | '-swap_to_user' \
| |
− | '-scopes' '${scopes}' \
| |
− | '-init' 'ADDLIBLE I2REST' \
| |
− | '-dcm_client_id' 'MYCLIENT'))"
| |
− | },
| |
− | * Анонимные сессии (*ANONYMOUS)
| |
− | * Варианты обычных сессий (system_XXX) - для задания особых параметров запуска, например логирования, запуск в выделенной подсистеме и прочее
| |
− | * Запуск сессии на удаленной машине (SBMRMTJOB)
| |
− | | |
− | = Настройка API =
| |
− | * Используем PCML, дать ссылку на что такое PCML, какие особенности PCML в i2Rest
| |
− | * Примеры PCML
| |
− | * Примеры расширенных PCML, включая тег openapi30
| |
− | = Настройка параметров доступа OAuth2 =
| |
− | == Модели настройки доступа ==
| |
− | Стандартная и custom модель, стандартная - бесплатная. Custom - позволяет настраивать собственные правила или справочники для пользователей, клиентов и токенов.
| |
− | == Стандартная модель ==
| |
− | === users ===
| |
− | === clients ===
| |
− | === scopes ===
| |
− | === tokens ===
| |
− | == Custom access model ==
| |
− | User exits для реализации custom модели
| |
− | == Standard UI pages ==
| |
− | i2Rest Server comes with a default set of web-pages to be shown to user in the user-server dialog (for example in Server and Client OAuth2 flows). You can use the snippet bellow as a default settings, just copy and paste them to your configuration file.
| |
− | <pre>
| |
− | "login_page" : "/pages/Login/index.html",
| |
− | "decision_page" : "/pages/user_decide.html",
| |
− | "bad_auth_page" : "/pages/bad_auth.html",
| |
− | "enter_code_page" : "/pages/enter_code.html",
| |
− | "device_connected_page" : "/pages/device_connected.html"
| |
− | </pre>
| |
− | Whenever you want to use pages with your own design - you are free to create them, place them on IFS and set up your config.
| |
− | ----
| |