i2Rest Advanced Setup

From i2Rest
Revision as of 11:33, 25 June 2020 by Pavel.lobko (talk | contribs) (→‎Request authorization)
Jump to: navigation, search

Let's proceed updating i2Rest Server configuration on the way to full functional server instance.

SSL

The first thing we recommend to add to a basic server configuration is a https protocol connections protection. Please follow detailed guide.

Request authorization

Most of requests to i2Rest Sever instance require authorization. Actually only Oauth2 token with appropriate scope to be served Let's observe i2Rest built-in authorization model configuration options.
Note: built-in authorization model implies all i2Rest Server users has to be registered as an IBM i users.
In general worlds authorization model is somenhing like WHAT is allowed and to WHOM, and HOW it realized. So WHAT allowed param - is scopes, HOW - tokens, WHOM params - users and clients. Look at simple template: 

{
   "curdir" : "/i2rest/1.0.0",
   "debug"  : 7, "syslog":"udp://localhost:514", 
   "gates":
   {
      "main"       : {"url":"https://api.i2rest.com:22088","dcm_server_id":"MYSERVER"},
      "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)"},
      {
         "name"   : "*LOCAL",
         "submit" : "SBMJOB JOB(I2RESTS) USER(${user}) CMD(CALL I2REST PARM('-session' '-url'  '${surl}'  '-uid'  '${uid}' '-user' '${user}' '-swap_to_user' '-init' 'ADDLIBLE I2REST' '-dcm_client_id' 'MYCLIENT'))"
      }
   ],
   "pcmls":
   [
      {
         "pcml_mount"         : "echo",
         "pcml_file"          : "/home/btpl/jpcml/i2restecho.pcml", 
         "valid_in_anonymous" : true
      }
   ],
   
   "OAuth2":
   {
      "scopes": {"run_program"          : {"description":"Run *PGM and *SRVPGM"}, 
                 "run_command"          : {"description":"Run CL command"},
                 "management_functions" : {"description":"Invoke i2Rest manager APIs"}},
      "users":
      {
         "BTPL":{"description":"Pavel Lobko",    "valid_clients":{"OAUTH21":{"scopes":["run_program", "run_command", "management_functions"]}}}
      },
      "clients":
      {
         "OAUTH21":{"redirect_uri":"https://api.i2rest.com:22088/oauth2/redirect", 
                    "description":"Test client", 
                    "valid_scopes":["run_program", "run_command", "management_functions"],
                    "valid_grant_types":["authorization_code", "urn:ietf:params:oauth:grant-type:device_code", "refresh_token", "client_credentials", "urn:i2rest:bridge:access_code"]}
      }
      
   }   
}
<pre>
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":"http://192.168.1.123:5678", ...},
       ...
    },
=== 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":"https://192.168.1.123:5678", "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"

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.

Retrieved from "https://www.i2rest.com/index.php?title=I2Rest_Advanced_Setup&oldid=1291"