OAuth2 object
TODO
Contents
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
Users
Clients
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:
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. |
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
