OAuth2 object

TODO

Built-in and external implementation

Some OAuth2 settings allow the use of a built-in (embedded) or external implementation.

• i2Rest Server Free edition allows to use built-in implementation only. This implementation uses a specific parameter structure and configuration principles. You can define the list of scopes, users or clients, set some parameters for code generation rules etc. All these parameters must be configured in the configuration file, and they will be unchanged from the moment the server starts. To change the settings, you must change the configuration file and restart the server. A detailed description of all parameters in embedded implementation is given below.
• With i2Rest Server Premium edition, you can develop your own custom implementation of functions for working with tokens, codes, scopes, users and clients. You can use any storage for this data, any algorithms and procedures, for example, to checking passwords, to querying permissions, to define valid scopes etc.

Settings for built-in implementation

Scopes

Use this parameter to define the list of scopes within this i2Rest Server instance. To define the scope, add following object to "scopes" object:

"<name of the scope>":{<scope definition object>}

For example:

"scopes": {"run_program"          : {"description":"Run *PGM and *SRVPGM"}, 
           "run_command"          : {"description":"Run CL command"},
           "management_functions" : {"description":"Invoke i2Rest manager APIs"}
}

Minimal scope list has to include "run_command", "run_program", "management_functions" scopes. If some of these scopes is absent, you will not able to use appropriate API. The structure of the definition object:

Field	Type	Description	Default value
description	string	Scope description

Token/Code generation rules

The following parameters control the rules for generating various kinds of codes. i2Rest Server generates the following codes:

• tokens
• refresh_tokens
• codes
• device_codes

To set the generation rule for some code, you must define it in the OAuth2 object:

"<code_name>":{<definition object>}

The structure of the definition object:

Field	Type	Description	Default value
type	string	Type of code This field defines major characteristics of token/code generation - code length, format and cryptographic algorithm to be used for code generation. Built-in implementation has following code types: "code" - generates 20 bytes random string using SHA1 "token" - generates 32 bytes random string using SHA256 "refresh_token" - same as "token" "user_code" - generates random code in format "XXXX-XXXX" Example: "token":{"type":"token"}	If "type" parameter not specified, "user_code" will be used.
capacity	integer	Capacity of internal tokens/codes storage Used to define the length of tokens/codes array to store generated values. The code/token is placed in an array at the time of generation, and is removed from it when used/presented. Old, unused codes removed from the list when "capacity" is reached and when it is required to put some new token/code to the list. Built-in implementation does not use persistent storage for generated codes/tokens. When the server stops, all codes will be lost	1000

Example:

"OAuth2": {
   ...
   "tokens"         : {"type":"token", "capacity":500},
   "refresh_tokens" : {"type":"refresh_token", "capacity":1000},
   "codes"          : {"type":"code", "capacity":100},
   "device_codes"   : {"type":"user_code", "capacity":200},
   ...
}

External implementation

In the case of using an external implementation, parameter setting is performed using an object of the following form:

"<parameter>" : {
   "implementation"  : "<service_program>",
   "init_entrypoint" : "<exported_function_name_used_for_initialize_object>",
   "config"          : <object_configuration_options>
}

Example:

"clients" : {
   "implementation"  : "I2REST/OAUTH2_CLI", 
   "init_entrypoint" : "OAuth2_client_init_internal", 
   "config"          : {
      "table" : "I2REST/CLIENTS"
   }
}

Mandatory property here is "implementation" - it should point to existing *SRVPGM object with code that implements functions specific for this parameter. As an example, for OAuth2 clients, it is required to provide *SRVPGM with following functions:

• init - initialize clients object
• destroy - destroys clients object
• get_client_copy - search client according implemented algorithm and return allocated copy of client data
• destroy_client_copy - deallocate copy of client data
• lock_client - search client and lock it for update. Returns pointer to client data
• update_client - update some details of client previously locked by lock_client function
• retrieve_client_credentials - retrieves encrypted version of client credentials
• validate_client_credentials - validates client credentials
• scopes_are_valid_for_client - validates that scopes are valid for the client
• grant_type_is_valid_for_client - validates that grant type is valid for the client

External implementation is available with i2Rest Server Premium edition. Objects that can be implemented externally are:

• tokens
• refresh tokens
• device codes
• user codes
• scopes
• clients, including client<>scope and client<>grant types relations
• users, including user<>clients relations

For detailed information about external implementation, please ask us

Other settings

Endpoints

• auth_endpoint
• access_endpoint
• decision_endpoint
• device_endpoint
• user_device_endpoint
• bridge_endpoint

Web pages

• login_page
• decision_page
• bad_auth_page
• enter_code_page
• device_connected_page
• bridge_enter_code_page
• bridge_completed_page

Miscellaneous parameters

• device_request_interval
• token_expires_in
• refresh_token_expires_in
• revoke_token_on_change_resource_owner_credentials
• revoke_token_on_scope_violation
• PKCE_mandatory