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

Users

This parameter allows to define the list of users for this i2Rest Server instance. In built-in implementation, all i2Rest Server users has to be registered as an IBM i users. i2Rest Server checks IBM i user passwords for authentication. When calling APIs, authorization settings configured on the IBM i server are used.
To set up a user, you must define it in the OAuth2 object:

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

The structure of the user definition object:

Field	Type	Description	Default value
description	string	User description
valid_clients	[valid_client]	List of clients who can work with this user (see below)
disabled	boolean	User is disabled? Setting to "true" allows you to temporarily prevent a user from working in the system	false

Elements of valid_users are defined as follows:

"<client_name>":{<valid_client_definition>}

The structure of the valid client definition object:

Field	Type	Description	Default value
scopes	[string]	List of scopes that can be used by this client when working with this user

Example:

"OAuth2": {
  ...
  "users":
  {
     ...
     "UDEMO":{"description":"Demo user", "valid_clients":{"CDEMO":{"scopes":["run_program", "run_command", "management_functions"]}}},
     "UTEST":{"description":"Test user", "valid_clients":{"CTEST":{"scopes":["run_program", "run_command", "management_functions"]}}}
     ...
  },
  ...
}

Clients

All OAuth2 clients that will interact with this server must be registered in the list. In built-in implementation, all i2Rest Server clients has to be registered as an IBM i user profiles. i2Rest Server checks IBM i user passwords for authentication of OAuth2 clients. When calling APIs, i2Rest Server uses authorization settings configured for user profiles related with OAuth2 user, authorization of user profiles related with OAuth2 clients does not matter. However, for the client to work, his user profile must be *ENABLED.
To set up a client, you must define it in the OAuth2 object:

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

The structure of the client definition object:

Field	Type	Description	Default value
description	string	Client description
redirect_uri	string	Client's redirect URI According to https://www.oauth.com/oauth2-servers/redirect-uris, Redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL. Because the redirect URL will contain sensitive information, it is critical that the service doesn’t redirect the user to arbitrary locations. You can define one redirect URI for each client. i2Rest Server will check and use this value during processing Authorization Code flows.
valid_scopes	[string]	List of scopes that can be used by this client
valid_grant_types	[string]	List of grant types that can be used by this client - zero or more of: "authorization_code" "refresh_token" "client_credentials" "urn:ietf:params:oauth:grant-type:device_code" "urn:i2rest:bridge:access_code" Grant types 1-5 corresponds to standard OAuth2 flows. Grant type "urn:i2rest:bridge:access_code" should be presented when this client would like to work in OAuth2 Authorization Code flow using i2Rest bridge mode

Example:

"Oauth2":{
   ...
   "clients": {
      ...
      "CDEMO": {
         "redirect_uri" : "https://api.i2rest.com/oauth2/redirect", 
         "description"  : "Demo 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"
         ]
      },
      ...
   },
   ...
}

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