Perun remote interfaces

Z MetaCentrum
Skočit na navigaci Skočit na vyhledávání

Back to Perun main page

Perun Interfaces

Interface for Humans

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

You can use Perun's new web interfaces that use OIDC and OAuth 2 at:

RPC Interface for Machine Access

RPC is an interface for remote access to Perun using standard HTTP/HTTPS calls. It is intended for calling by programs. The RPC interface is described using machine-processable document in OpenAPI format, so you can generate client libraries in many programming languages using OpenAPI Generator.

Or you can write a client library by hand. However the RPC interface contains more than 700 operations, so it can be time consuming.

RPC OpenAPI Description

The OpenAPI document describing Perun RPC is available here:

https://github.com/CESNET/perun/tree/master/perun-openapi

There are prepared clients in several languages:

The server API is located at https://perun-api.e-infra.cz/ and supports the following authentication methods:

  • HTTP basic auth or Kerberos ticket - https://perun-api.e-infra.cz/krb/rpc/
  • OAuth 2 access token - https://perun-api.e-infra.cz/oauth/rpc/

The HTTP basic auth method needs to use e-INFRA.cz login and password.

The Kerberos ticket needs to be from the EINFRA realm, you can use your personal one.

For obtaining an OAuth 2 access token you need a registered OAuth client, and to use an appropriate grant flow.

  • For command-line clients, we recommend using Device Code grant flow, an example in Python is available in perun-cli-python/perun/oidc/__init__.py
  • For javascript Single Page Applications (SPA) we recommend Authorization Code grant flow with PKCE
  • For server-side web applications we recommend Authorization Code grant flow

RPC Description for Human Programmers

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... });

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
Citováno z „https://wiki.metacentrum.cz/w/index.php?title=Perun_remote_interfaces&oldid=13245“