pci

Developer credential protected methods to create picos, manage rulesets, and create ECI

Related modules

The following modules are related to the PCI module and use the same credentialling and permissioning regime.

Pico IDs

Many of the functions and actions in the PCI module require an argument that is called an "pico ID." This can be satisfied in one of two ways:

1. All accounts on a given instance of KRE have a unique user identifier which is a serial number for the account. This can be used an identifier for the primary pico in a given account. 
2. Every pico is given a default ECI when it is created and using the tools in this module, developers can give a pico any other ECIs that are desirable. In addition, some system functions create ECIs for the pico. Any of these ECIs can be used as an pico ID.

Using Credentials

Kynetx will issue the developer credentials which should be included in the ruleset meta function

meta {  
  keys "system_credentials" { 
    "developer_eci"      : <string>,
    "developer_secret"   : <string>
  }
}

Picos

new_pico

Create a new account (requires system permissions)

<map>:

• username : <string>
• firstname  : <string>
• lastname  : <string>
• password  : <string>        // may be left blank for a linked account
• label: <string>
  

On success

If the developer provides an ECI, the new pico will be created with a link to the ECI as the <parent> pico. Linked picos may include password optionally. Authorization for linked picos without passwords will default to the <parent>'s pico credentials.  Failure to provide a password for a top level pico will result in an unusable/defunct pico so don't do that.

The default ECI that is created via new_pico has a label of _LOGIN for a unlinked pico and _CHILD for a linked pico. 

response = pci:new_pico({
	"username" : "MrFingers34",
	"firstname" : "Bill",
	"lastname" : "Last",
	"password" : "teledoomrefract"})
 
response = pci:new_pico("eci_string_long_UUID");

delete_pico

Deletes an pico  (requires system permissions)

<map>:

• cascade : 0|1

On success

An ECI is required. The pico, configuration and associated ECIs are deleted.  By specifying the {"cascade" : 1} option, all of the linked/dependent picos will also be deleted. Deleting a dependent pico will NOT delete the linked parent pico

undef = pci:delete_pico("eci_string_long_UUID",{"cascade" : 1})
 
undef = pci:delete_pico("eci_string_long_UUID");

myChildren = pci:list_children();           		// Defaults to current session's pico
myChildren = pci:list_children({"user_id" : 41305});    // Children for user 41305
myChildren = pci:list_children(41305);                  // Children for user 41305
 

myParent = pci:list_parent();           	      // Defaults to current session's pico
myParent = pci:list_parent({"user_id" : 41305});      // Parent for user 41305
myParent = pci:list_parent(41305);                    // Parent for user 41305
 

myParent = pci:set_parent("eci_child_UUID","eci_newOwner_UUID");      // Defaults to current session's pico

 

Ruleset Functions

new_ruleset

Adds one or more rulesets to the cloud specified by <pico id> (requires developer [ "ruleset", 'create" ] permissions)

<pico id> :

• <userid> | <eci>

<rid list> : 

• <string>
• [<string0>, <string1>, .., <stringn>]

response = pci:new_ruleset(41305,"a144x101");  
 
response = pci:new_ruleset("eci_string_long_UUID",["a144x101","a169x843","a16x61"]);
 

Does this mean that '.' can't be used in a <rid>? Yes.

delete_ruleset

Deletes one or more rulesets from the cloud specified by <pico id> (requires developer [ "ruleset", "destroy" ] permissions)

<pico id> :

• <user id> | <eci>

<rid list> : 

• <string>
• [<string0>, <string1>, .., <stringn>]

response = pci:destroy_ruleset(41305,"a144x101");  
 
response = pci:destroy_ruleset("eci_string_long_UUID",["a144x101","a169x843","a16x61"]);
 

Developer credential protected methods to create picos, manage rulesets, and create ECI

list_ruleset

lists the rids installed to the pico specified by <pico id> (requires developer [ "ruleset", "show" ] permissions)

<pico id> :

• <user id> | <eci>

response = pci:list_ruleset("eci_string_long_UUID");

ECI Functions

new_eci

Create a new ECI for the pico specified by <pico id> (requires developer [ "eci", "create" ] permissions)

<pico id> :

• <user id> | <eci>

response = pci:new_eci();       // creates an ECI for the session user
 
response = pci:new_eci(41305,{"name" : "general foo's token exchange");  // creates an ECI for userid/NID 41305

delete_eci

Deletes the ECI specified (requires developer [ "eci", "destroy" ] permissions)

<pico id> :

• <eci>

response = pci:delete_eci("eci_string_long_UUID");

list_eci

Lists the ECIs assigned to <user id> (requires developer [ "eci", "show" ] permissions)

<pico id> :

• <user id> | <eci>

response = pci:list_eci("43567");
response = pci:list_eci();

get_eci_type()

Get the type of the ECI.

set_eci_type()

Set new type for the ECI.

get_eci_attributes()

Get any attributes stored with the ECI.

set_eci_attributes()

Set new attributes to be stored with the ECI.

To update attributes, you must retrieve the existing attributes with get_eci_attributes(), modify the result, and then use set_eci_attributes() to set it as a new attributes

get_eci_policy()

Get a policy stored with the ECI.

set_eci_policy()

Set new policy to be stored with the ECI.

To update a policy, you must retrieve the existing policy with get_eci_policy(), modify the result, and then use set_eci_policy() to set it as a new policy.

session_token

Get the primary or "login" eci associated with an ECI or <user id> (requires developer [ "eci", "show" ] permissions)

<pico id> :

• <user id> | <eci>

primary = pci:session_token("43567");
primary = pci:session_token("eci_string_long_UUID");

OAuth Applications 

Developers can register Web applications to use OAuth to access picos. The functions and actions documented below make that possible. 

Application Lifecycle

register_app()

The regsister_app() action registers a new OAuth application. It takes the following parameters:

The action also accepts the following optional parameters (declared using the with syntax):

All of the options can be set, updated, or deleted separately using other functions in this section. 

This action creates a developer token and secret that can be used to call other functions in the PCI module. The developer token is given default permissions (set by the configuration of the KRE instance you're operating on). 

The action supports the optional setting clause that gives the names of the variables in which the the token and secret be stored. The first variable will be the token and the second the secret. This variable is available to any expression executed after the action takes place: expressions in the parameters of later actions or in the postlude of the rule. Exercise care that the secret is not inadvertently exposed. 

Example: 

pci:register_app(<pico id>) setting(token, secret)
   with name = "Oauth App 2" and
 	    icon = "http://example.com/default.png" and
	    description = "Second Oauth App for Testing" and
	    info_url = "http://example.com/info" and
	    declined_url = "http://example.com/declined" and
        callbacks = ["http://example.com/callbacks"] and
	    bootstrap = ["b16x876.prod"]

delete_app()

The delete_app() action deletes the app registration identified by the developer token passed in as the only parameter.

list_apps()

The list_apps() lists all of the registered applications for the identified user.

The return result is a map with developer tokens as keys and the value being another map of information stored about the application (see register_oauth_app() above) plus the developer secret. 

OAuth Callback Management

add_callback()

Add a callback url for an OAuth enabled application

The array <callback uri> the form has [<url0>, <url1>, .., <strN>] 

On success value [str0, str1, .., strN] 

Pre-authorize one or more URIs that will be used in the OAuth authorization process. The exact <developer token> must be used with the callback or the request will be rejected.

cbs = pci:add_callback("eci_string_long_UUID",["http://www.example.com"]); 
cbs = pci:add_callback("eci_string_long_UUID",["http://www.example.com", "https://secure.example.com/oauth/"]); 

remove_callback()

Remove a callback url for an OAuth enabled application 

On success value

[str0, str1, .., strN] 

Remove an URI from the list of callbacks authorized for an application 

remaining_callbacks = pci:remove_callback("eci_string_long_UUID","https://secure.example.com/oauth/");

list_callback()

List callback urls for an OAuth enabled application

Returns the list of callback URLs authorized for an application

 callbacks = pci:list_callback("eci_string_long_UUID"); 

Bootstrap RID Management

add_bootstrap()

Add a bootstrap (default) ruleset for an OAuth enabled application. A bootstrap ruleset should include all of the configuration information and logic needed to configure the user pico for the OAuth enabled application

Returns an array of RIDs.

Configure a ruleset that will be added to an pico, when the user signs up or authorizes an OAuth-enabled application

cbs = pci:add_bootstrap("eci_string_long_UUID","b144x123.prod");

remove_bootstrap()

Remove a (default) ruleset for an OAuth enabled application

Returns the new list of bootstrap RIDs. 

Remove a ruleset from the list of callbacks authorized for an application 

 remaining_bootstrap = pci:remove_bootstrap("eci_string_long_UUID","b144x123.prod");

list_boostrap()

List the bootstrap (default) rulesets for an OAuth enabled application

Return the list of bootstrap rulesets for an application 

 callbacks = pci:list_bootstrap("eci_string_long_UUID");

OAuth Application Information Management

add_appinfo()

Add configuration information for the OAuth authorization process–particularly the authorization page that notifies the user which app wants access to the user's pico       

The options map can contain the following values:

The function returns the number of fields added. 

num_fields = pci:add_appinfo("eci_string_long_UUID", { 
	'icon' : 'https://squaretag.com/assets/img/st_logo_white_trans.png', 
	'name' : "Burt's Magic Fingers", 
	'description' : "Application requests access to: profile information", 
	'info_page' : 'http://www.exampley.com' 
 } 
);

get_appinfo()

The get_appinfo() function lists options defined for an OAuth-enabled ruleset

Returns the configured options as a map. 

 appinfo = pci:get_appinfo("eci_string_long_UUID");

remove_appinfo()

The remove_appinfo() function deletes all application information defined for an OAuth-enabled ruleset

appinfo = pci:remove_appinfo("eci_string_long_UUID"); 

Authorization

auth

Compares the supplied password with the hash stored in the database (requires developer ["cloud", "auth"] permissions)

<pico id> : <string>

<pico id> : 

• username : <string>
• user_id      : <string>
• eci             : <eci>

authed = pci:auth("MrFingers34","teledoomrefract");           // default <username>,<password>
 
authed = pci:auth("teledoomrefract");                         // uses current session user for authorization target
 
authed = pci:auth({"user_id" : 41305},"teledoomrefract");    

exists

Checks the KRE database to see if the supplied username is already in use (requires system permissions)

<pico id> : <string>

<pico id> : 

• username : <string>
• user_id      : <string>
• eci             : <eci>

is_taken = pci:exists("MrFingers34");           // default <username>,<password>

is_set = pci:set_password("teledoomrefract","myN3wpasswOrd");           // sets a new password for session user 
 
is_set = pci:set_password("MrFingers34","teledoomrefract","myN3wpasswOrd");  // sets a new password for user "MrFingers34" 
 
is_set = pci:set_password({"user_id" : 41305},"teledoomrefract","myN3wpasswOrd");  // new password for user_id/NID 41305  

is_set = pci:set_password("myN3wpasswOrd");                        // sets a new password for session user 
 
is_set = pci:set_password("MrFingers34","myN3wpasswOrd");          // sets a new password for user "MrFingers34" 
 
is_set = pci:set_password({"user_id" : 41305},"myN3wpasswOrd");  // new password for user_id/NID 41305  

username = pci:get_username({"user_id" : 41305});           

user_email = pci:get_email({"user_id" : 41305});           

Administration functions

create_developer_key

Create developer credentials (requires system permissions)

<pico id> :

• <eci>

secret = pci:create_developer_key();
 
secret = pci:create_developer_key("eci_string_long_UUID");

isset = pci:set_permissions("eci_string_long_UUID","secret_UUID",["ruleset", "create"]);

isset = pci:clear_permissions("eci_string_long_UUID","secret_UUID",["ruleset", "destroy"]);

isset = pci:get_permissions("eci_string_long_UUID","secret_UUID",["eci", "destroy"]);