Perun remote interfaces

Z MetaCentrum
Přejít na: navigace, hledání

Back to Perun main page

GUI

You can log in to Perun's graphical web interface using three different authentication methods:

using MetaCentrum Kerberos - Perun GUI
using Federation identity - Perun GUI
using IGTF Certificate - Perun GUI

RPC

RPC is an interface for remote access to Perun using standard HTTP/HTTPS calls. RPC expect you to use GET type of requests for read only methods and POST type of requests for any state changing method (create, update, delete,...).

URL structure of each RPC call is following:

https://base_url/authz_type/perun_component/data_exchange_format/managerName/methodName?param1=value&param2=value&listParam[]=value1&listParam[]=value2

RPC server location + authz

Following base URLs are provided, each uses different authentication method to log you in. Please note, that if you run your own Perun instance, base URL is different.

https://perun.metacentrum.cz/krb/rpc/ (using Kerberos from realm @META/@EINFRA)
https://perun.metacentrum.cz/krbes/rpc/ (using Kerberos from realm @EINFRA-SERVICES)
https://perun.metacentrum.cz/fed/rpc/ (using credentials from your federation IdP)
https://perun.metacentrum.cz/cert/rpc/ (using IGTF certificate)

Data exchange formats

Following formats are supported for data exchange: JSON, JSONP and VOOT (soon). You can specify format in URL following example:

https://perun.metacentrum.cz/krb/rpc/json/
https://perun.metacentrum.cz/krb/rpc/jsonp/
https://perun.metacentrum.cz/krb/rpc/voot/ (not yet deployed)

JSONP uses padding before and after data to help you match call and it's response. Then, all requests must contain parameter callback=matcher and returned value is in a format: matcher(standard_json_data);. If callback matcher is not provided, then null(standard_json_data); is returned instead. If parameter is empty, then (standard_json_data); is returned. If returned value is not an object, but single value like: string, number or boolean, then matcher(value); is returned (e.g. matcher(false); or matcher("text");).

Calling a method

In order to call any method you must provide manager's and method's name in request URL. Both of them use CamelCase in their names.

List of available methods can be found in RPC's javadoc.

https://perun.metacentrum.cz/krb/rpc/json/vosManager/getVos
# will give you list of your VOs in JSON format

You must use POST for calling state changing methods (create, add, assign, update, delete, remove,...). You can use GET (or POST) for all other methods, which just reads data from Perun (get, find, list,...). Exception is thrown if HTTP request is of different type than method accepts.

Passing parameters to methods

GET

Location: All parameters must be present in HTTP request URL. Request body is ignored.
Accept: string, integer and list (of strings and integers)
Format: First parameter in URL starts with ?, others with &. List parameters uses [] after parameter's name and parameters are repeated for every value of list: ?listParam[]=value1&listParam[]=value2.

https://perun.metacentrum.cz/krb/rpc/jsonp/vosManager/getVoById?callback=call1&id=123
# will give you VO by it's ID = 123 in JSONP format
# response like: call1({"name":"vo_name_value","shortName":"vo_short_name_value", "id":123, "beanName":"Vo", ...other vo params... });

POST

Location: All parameters must be passed in HTTP request body.
Accept: any type of correctly defined data / objects
Format: defined by data_exchange_format Please note, that JSONP also expect JSON data, since padding definition is part of the request URL.

For JSON/JSONP to pass set of parameters simply create empty JSON object and fill it with properties with names mathing method's parameters and values matching method parameter's types. When passing whole object to method, some of it's properties might be ignored (and not required to be present). E.g. beanName which is property defining object type. It is contained in objects returned to you, but not required when posting object back to Perun.

URL: https://perun.metacentrum.cz/krb/rpc/jsonp/vosManager/addAdmin?callback=call2
DATA: {"vo":123, "user":1234}
# if method requires simple integer parameters with names 'vo' and 'user' like method vosManager/addAdmin
# response like: call2(null); (since method doesn't return anything)

Error handling

When using JSON or JSONP data exchange format, all calls ending with an error are returned as OK (HTTP return code 200). This allow you to process returned exception serialized in expected format (otherwise browsers throw away error responses and your application wouldn't know what's wrong).

e.g. callbackPost({"name":"exception_name", "message":"exception_message", "errorId":"1428f68a462" ...other optional parameters... });

PHP Library

Simple PHP Perun binding. PerunRpcClient.php and examples can be downloaded from GitHub https://github.com/CESNET/perun/tree/master/perun-php.

Prerequisities

Install PHP support and curl extension for Apache:

 sudo apt-get install php5-curl libapache2-mod-php5

Setup Apache to run CGI scripts in folder with your app:

  Options Indexes MultiViews Includes ExecCGI FollowSymLinks
  AddHandler cgi-script .php

Configuration

Edit PerunRpcClient.php and adjust next options:

 // PERUN RPC URL
 const RPC_URL = "https://perun.cesnet.cz/krb/rpc/json/";
 // Choose the authentication method:
 // Username
 const USER = "perun-client";
 // Password based authentication, left empty if you are using Kerberos authz
 const PASSSWORD = "";
 // Kerberos based authentication, left empty if there is no Kerberos support
 const KERBEROS_CC = "/tmp/krb5cc_perun-client";

For local development you can set USER to "your_login@REALM" and PASSWORD as your kerberos password. Then keep KERBEROS_CC empty. This is not secured solution !!

Calling a method

In order to call any method you must provide manager's and method's name. Both of them use CamelCase.

List of available methods can be found in RPC's javadoc.

include ("PerunRpcClient.php");

Initialize the Perun Client

$client = new PerunRpcClient();

Method without parameters

$vos = $client->retrieveData("vosManager/getVos");

Method with parameters

$params = array('vo' => 21);
$members = $client -> retrieveData("membersManager/getRichMembers", $params);

If something failed, retrieveData() will return false.

if($members === false){
    print "Error while getting response.";
    exit;
}

Process the results

 foreach($vos as $vo){
   print {$vo->id};
   print {$vo->shortName};
   print {$vo->name};
 }
 foreach($members as $richMember){
   print {$richMember->user->firstName};
   print {$richMember->user->lastName};
 }

JavaScript Library

For using you will need configuration.js, where will be specificated rpc_url.

More about rpc_url here.

Configuration = {
   RPC_URL : "https://perun.metacentrum.cz/fed/rpc/jsonp/",
}

In order to call any method you must provide manager's and method's name to url. Both of them use CamelCase.

List of available methods can be found in RPC's javadoc.

$.ajax({ 
url : Configuration.RPC_URL + "groupsManager/getGroupRichMembersWithAttributes",
data : {
group : 817
},
success : function(data, textStatus, jqXHR)
{
if(typeof data.errorId !== "undefined")
  {
    alert(data.errorText);
  }else{
    
    //definition of table
    var table = PerunTable.create();
    table.addColumn("user.id", "ID");
    table.addColumn("user.firstName", "First name");
    table.addColumn("user.lastName", "Last name");
    
    // adds the values to the table
    table.add(data);
    
    //create html from table
    var tableHtml = table.draw();
    
    //add table to specific div element
    $("specificDiv").html(tableHtml);
  }
},
               
dataType: "jsonp",
type : "get"
})

Class PerunTable is easy way to visualize accepted data.

Synchronization a group with external resource

SQL query returning column firstName, lastName, login. Optionally middleName, titleBefore, titleAfter. SQL query could return columns with names of concrete attributes. Due to size restriction, attribute names must be shorten, where x:y:z means:

x meaning
m member
u user
f facility
r resource
g group
v vo
h host
mr member_resource
uf user_facility
gr group_resource


y meaning
d def
o opt

Examples:

m:d:address -> urn:perun:member:attribute-def:def:address
u:d:login-namespace:mu -> urn:perun:user:attribute-def:def:login-namespace:mu
  • Example groupMembersQuery for external resource SQL database cz.metacentrum.perun.core.impl.ExtSourceSql
select name as first_name, surname as last_name, login, mail as "m:d:mail", telephone as "m:d:phone" 
from someTable
  • Example groupMembersQuery for external resource LDAP cz.metacentrum.perun.core.impl.ExtSourceLdap
TBA
  • Example groupMembersQuery for external resource ISMU cz.metacentrum.perun.core.impl.ExtSourceISMU
https://is.muni.cz/auth/export/skupina_osob.pl?format=csv&kodovani=utf-8&skup_zkratka=1433:15

How to create a synchronized with external resource PERUNPEOPLE type SQL with five minute interval:

./setGroupAttribute --groupId 123 --attributeName 'urn:perun:group:attribute-def:def:groupExtSource' --attributeValue PERUNPEOPLE
./setGroupAttribute --groupId 123 --attributeName 'urn:perun:group:attribute-def:def:groupMembersQuery' --attributeValue 'select name as first_name, surname as last_name, login, mail as urn:perun:member:attribute-def:def:mail, telephone as urn:perun:member:attribute-def:def:phone from someTable'
./setGroupAttribute --groupId 123 --attributeName 'urn:perun:group:attribute-def:def:synchronizationEnabled' --attributeValue true
./setGroupAttribute --groupId 123 --attributeName 'urn:perun:group:attribute-def:def:synchronizationInterval' --attributeValue 1

Manual synchronization

./synchronizeGroup --groupId 123