I2Rest Advanced Setup

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. IBM i command call, [I2Rest_API#run_program_API|API call] (except anonymous API call, can be peformed witho 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.

---