OAuth2 object

Built-in and external implementation

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

• i2Rest Server Free edition allows to use only built-in implementation of OAuth2 parameters. 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 setting and validation of 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 to take part in OAuth2 flows	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

i2Rest Server listens for incoming connections at several endpoints related to main or management gates. All these endpoints has default values that can be overridden in configuration file
Endpoints must vary. Endpoint cannot be the beginning of another endpoint. Endpoints must be valid URL path component

Endpoint	Purpose	Flows	Default value
auth_endpoint	This is Authorization Endpoint of i2Rest Server	Authorization Code	/oauth2/auth
access_endpoint	This is Token Endpoint of i2Rest Server	Authorization Code Client Credentials Device Code Refresh Token Authorization Code (i2Rest bridge mode)	/oauth2/access
decision_endpoint	At this endpoint, the user will be able to authenticate himself and to decide whether he grants or denies the client's access request	Authorization Code	/oauth2/user_decision
device_endpoint	This is Device Authorization Endpoint of i2Rest Server	Device Code	/oauth2/device
user_device_endpoint	This is User Interaction Endpoint of i2Rest Server	Device Code	/device
bridge_endpoint	This is Bridge Endpoint of i2Rest Server This endpoint is not available at management gate	Authorization Code (i2Rest bridge mode)	/a2d

Web pages

i2Rest Server at some points in the flows interacts with the user. Server installation includes the simplest versions of pages with a user interface. During the implementation process, you can change or create your own versions of pages, and specify their addresses in the configuration file.
Pages and static content can be placed and served by i2Rest Server, or you can use an external web server or web application.
To place static content on the i2Rest Server, it must be placed in the Static/ folder in the current server directory (see configuration parameter curdir). In this case, static content will be available as a resource at http(s)://<i2Rest_server_name:port>/pages/<resource_path_at_Static>, for example:

Static/device_connected.html => http://myserver.com/pages/device_connected.html
Static/Login/index.html => http://myserver.com/pages/Login/index.html

Pages representing external links must be specified as a complete URL path in configuration file.
User interaction pages that can be specified in configuration file:

Page	Purpose	Flows	Default value
login_page	i2Rest Server will use this page to authenticate users (resource owners)	Authorization Code Device Code Authorization Code (i2Rest Bridge mode)	/pages/Login/index.html
decision_page	This page is used in Authorization Code flows (including i2Rest Bridge mode), to ask the resource owner about a decision for providing access to the client.	Authorization Code Device Code Authorization Code (i2Rest Bridge mode)	/pages/user_decide.html
bad_auth_page	This page is used in Authorization Code flows, to inform resource owner about invalid request: missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid	Authorization Code	/pages/bad_auth.html
enter_code_page	i2Rest Server uses this page in Device Code flow to show dialog where user is able to enter User Code and allow or deny access for device that started this flow	Device Code	/pages/enter_code.html
device_connected_page	This page is the last UI in successful Device Code flow. i2Rest Server will reply with this page when user grants access for the client	Device Code	/pages/device_connected.html
device_denied_page	This case is opposite to previous. i2Rest Server will reply with this page when user denies access for the client	Device Code	/pages/device_denied.html
bridge_enter_code_page	This page is used in Access Code flow (i2Rest Bridge mode) to show dialog for entering Bridge User code before redirecting to decision page	Authorization Code (i2Rest Bridge mode)	/pages/bridge_enter_user_code.html
bridge_completed_page	This page is the last page in Access Code flow (i2Rest Bridge mode). It is displayed when user grants access to client	Authorization Code (i2Rest Bridge mode)	/pages/bridge_completed.html
bridge_denied_page	This page is opposite to previous. It is displayed when user denies access to client	Authorization Code (i2Rest Bridge mode)	/pages/bridge_denied.html

Miscellaneous parameters

Field	Type	Description	Default value
device_request_interval	integer	Device request interval Used to configure the interval (in seconds) at which the device should poll the server for a token. If the device will poll the server more often, the server will return a message "slow_down"	5
token_expires_in	integer	Default token expiration time in seconds	3600
refresh_token_expires_in	integer	Default token expiration time in seconds for refresh tokens	604800 (7 days)
revoke_token_on_change_resource_owner_credentials	boolean	Should i2Rest Server revoke issued tokens when resource owned changed his password?	false
revoke_token_on_scope_violation	boolean	Should i2Rest Server revoke all tokens issued for some client, when this client requests token with scope that is not valid for this client?	false
PKCE_mandatory	boolean	Is PKCE mode mandatory? i2Rest Server supports RFC 7636: Proof Key for Code Exchange. This specification describes a technique to mitigate against the threat through the use of Proof Key for Code Exchange. The specification adds additional parameters to the OAuth 2.0 Authorization and Access Token Requests. When PKCE is set to mandatory, then i2Rest Server will require clients to follow RFC 7636 specification.	false