Tags:
create new tag
, view all tags

nethz Web Services

SMS - Gateway

  • Base-URI: https://idn.ethz.ch/send_sms
  • nethz SMS Service ist Voraussetzung für die Benutzung dieses Services
  • Absender-Text oder Absender-Telefonnummer ist frei wählbar
  • alle Verbindungen sind mit Basic Authentication geschützt
  • Message-Länge ist momentan auf 2000 Zeichen limitiert
  • Daten werden immer im JSON-Format übertragen (d.h. UTF-8 encodiert)
  • Beispiel mit curl
  • curl --user username:password --data '{ "from": "0041791234567", "message": "this is the message" }' https://idn.ethz.ch/send_sms/0041761234567

HTTP verb URI Body Beschreibung
POST /username
{ 
    "from": "0041798765432", 
    "message": "sms message"
}
Die Person des angegebenen Users muss eine Handynummer registriert haben, damit eine SMS gesendet werden kann
POST /0041798765432
{ 
    "from": "0041791234567",
    "message": "sms message"
}
anstelle des Usernamens kann der Empfänger direkt angegeben werden
POST /+41798765432
{ 
    "from": "+41791234567",
    "message": "sms message"
}
eine weiter Möglichkeit, die Telefonnummer anzugeben
POST /0798765432
{ 
    "from": "abcdefghijk",
    "message": "sms message"
}
wird automatisch mit 0041 ergänzt und die lokale Vorwahl entfernt. Max. 11 Zeichen anstelle einer Absender-Telefonnummer.

usermgr – User- und Sevicemanagement

  • alle Return-Werte immer in JSON
  • die Verbindung ist immer https (wird vom Webserver so gesteuert)
  • alle POST-Verbindungen sind mit Basic Authentication gesichert
  • Base-URI: https://idn.ethz.ch/usermgr

Informationen auslesen

HTTP verb URI Body Beschreibung
GET /person?param=value&param2=value2   Array mit Daten der Person (siehe unten)
GET /person?leitzahl=06006   Suche nach Leitzahl. Returns: Array mit Daten der Person (siehe unten)
GET /person?pnr=33018   Suche nach Personal-Nummer (nicht zu verwechseln mit der PERSID=Personen-ID). Returns: Array mit Daten der Person (siehe unten)
GET /person/[NPID, nethz-username, email]
{
   "firstname" : "Surname",
   "familyname" : "Given Name",
   "title" : "Frau Dr. Prof",
   "npid" : "123456",
   "persid" : "98877656",
   "primary_username" : "nethz_username",
   "usernames" : [
      {
         "username" : "nethz_username",
         "uid_number" : 76589643,
         "gid_number" : 876687,
      },
      {
         "username" : "nethz_username2",
         "uid_number" : 786868,
         "gid_number" : 67868,
      }
    ],
   "primary_perskat" : "Dozent",
   "perskats" : [
      {
         "perskat" : "Mitarbeiter",
         "von" : "2013-01-01",
         "bis" : "2016-12-31"
      }
      {
         "perskat" : "Dozent",
         "von" : "2013-01-01",
         "bis" : "2016-12-31"
      }
   ]
}
gibt für eine bestimmte Person Detailinformationen zurück
GET /user/[nethz_username]
{
    "login_shell": "/bin/bash",
    "cre_date": "11-APR-2000",
    "npid": "456456",
    "uidNumber": "234563",
    "valid_until": "31-DEC-9999",
    "nuid": "65456",
    "init_passwd_set": "0",
    "home_directory": "/home/testuser",
    "enabled": "1",
    "userPrivateGroupID": "92941",
    "mod_date": "02-MAR-2012",
    "memo": "used for tests",
    "username": "testuser",
    "cre_by": "somebody",
    "gidNumber": "65436",
    "mod_by": "anotherbody"
}
gibt für einen bestimmten User Detailinformationen zurück
GET /user/[nethz_username]/services
[
   "CQ5": {
      "login_until": "31-DEC-9999",
      "delete_after": "31-DEC-9999"
   },
   "Bibliothek": {
      "login_until": "31-DEC-9999",
      "delete_after": "31-DEC-9999"
   },
   "Mac": {
      "login_until": "31-DEC-9999",
      "delete_after": "31-DEC-9999"
   }
]
Service-Informationen dieses Users

User erstellen und löschen

HTTP verb URI Body Beschreibung
DONE POST person/[NPID, nethz-username, email]/user
{
    "username" : "new_username",
    "memo" : "weshalb warum",
    "init_passwd": "$ecure" 
}
Einen neuen User für eine bestimmte Person erstellen. Die Person muss dabei eindeutig identifizierbar sein (NPID, Username, E-Mail)
TODO PUT /user/[nethz_username]
{
    "memo" : "new memo",
    "init_passws": "eVenMore$ecure"
}
Attribute eines Users anpassen
TODO PUT /user/[nethz_username]
{
    "password" : "meinSupernethzPasswort" 
}
Supernethz-Passwort für diesen Usernamen setzen

Services erteilen, anpassen und entziehen

HTTP verb URI Body Beschreibung
POST /user/[nethz_username]/service/[nethz_service]   beliebigen nethz-Service mit Standard-Einstellungen erstellen
POST /user/[nethz_username]/service/Mailbox
{
    "sn" : "Nachname",
    "givenName" : "Vorname",
    "displayName" : "First Last",
    "description" : "this is a description",
    "mail" : "first.last@ethz.ch",
    "isHidden" : true,
    "noMailReceive" : false,
    "forward" : "send_mails_to@example.com",
    "quota" : "5GB",
    "homeDrive" : "Z:",
    "homeDirectory" : "\\zo-tri-home\home$\uvw\vermeul$",   
    "profilePath" : "\\d\dfs\users\all\vermeul\%pafs%",
    "unixHomeDirectory" : "/nas/vermeul",
    "loginShell" : "/bin/bash",
    "primaryGroup" : "Domain Users",
}
Mailbox-Service erteilen (mit Service-Parametern)
PUT /user/[nethz_username]/service/Mailbox
{
    "sn" : "Nachname",
    "givenName" : "Vorname",
    "displayName" : "First Last",
    "description" : "this is a description",
    "homeDrive" : "Z:",
    "homeDirectory" : "\\zo-tri-home\home$\uvw\vermeul$",   
    "profilePath" : "\\d\dfs\users\all\vermeul\%pafs%",
    "unixHomeDirectory" : "/nas/vermeul",
    "loginShell" : "/bin/bash",
}
Mailbox-Serviceparameter ändern
PUT /user/[nethz_username]/service/Mailbox { "primaryGroup" : "Domain Users" } primäre Gruppe auf «Domain Users» setzen (oder sonst eine bestehende Security-Gruppe)
PUT /user/[nethz_username]/service/Mailbox { "forward" : "other.mailbox@example.com" } Forward setzen
PUT /user/[nethz_username]/service/[nethz_service] { "password" : "strenggeheim" } Passwort für beliebigen nethz-Service setzen
PUT /user/[nethz_username]/services { "password" : "strenggeheim" } Passwort für alle nethz-Services setzen
PUT /user/[nethz_username]/service/[nethz_service] { "enabled" : 0 } nethz-Service eines bestimmten Users sperren
PUT /user/[nethz_username]/services { "enabled" : 0 } alle nethz-Services eines bestimmten Users sperren
DELETE /user/[nethz_username]/service/[Service Name]   einen spezifischen nethz-Service einem nethz-User entziehen.
DELETE /user/[nethz_username]/services   alle nethz-Services dieses Users entziehen

HomeDirectory-Service

Allgemeines

  • ein Home Directory ist im Wesentlichen ein File-Share
  • Home Directories werden heute über eine Blackbox im Hintergrund angelegt – und zwar für alle AD-User (service AD / Mailbox)
  • ein Home Directory Service ist essentiell, um auf Storage-Seite den Share explizit anzulegen und auch zu löschen, oder Berechtigungen zu korrigieren
  • die Shares sollen nicht mehr über den Umweg des AD/NAS-OS erstellt werden sondern explizit
  • das Löschen von alten Home Directories war in der Vergangenheit immer ein Knackpunkt
  • der Home Directory Service soll den bisherigen NAS-DFS Service ersetzen
  • Homedirectories können mit dierem neuen Verfahren auch 'on Demand' erstellt werden
  • Inhalte von Kursaccount Homedirectories können geleert (recreate) werden

ausgeführte Arbeiten

  • bestehender NAS-DFS Service in Home Directory Service überführen / umbenennen
  • alle bestehenden Shares zusätzlch mit einem expliziten Home Directory Service versehen (v.a. Mitarbeiter!)
  • Home Directory Service standardmässig für alle Studenten einrichten
  • Home Directory Service für übrige Personenkategorien (Mitarbeiter, Dozenten, ETH-nahe, ETH-Gäste) standardmässig einrichten
  • TODO beim Einrichten des Home Directory Service sollen die entsprechenden AD-Parameter korrekt gesetzt werden
  • Verfahren festlegen, wie Kursaccounts gehandhabt werden
  • Status-Texte für Aufgaben lauten wie folgt:

    • create HomeDirectory 2016-02-23 11:53:00 Share initial anlegen
    • delete HomeDirectory 2016-02-23 11:53:00 Share definitiv löschen
    • register HomeDirectory 2016-02-23 11:53:00 Service (auf Seite nethz) explizit erteilen (existierender Share)
    • recreate HomeDirectory 2016-02-23 11:53:00 HomeDirectory löschen und neu anlegen (delete, create)
    • assign HomeDirectory 2016-02-23 11:53:00 fehlerhafte Berechtigungen des Shares mit default-Berechtigungen überschreiben, ohne dessen Inhalt zu löschen
  • Status-Texte für erledigte Aufgaben lauten wie folgt:

    • 'register' => 'register Homedirectory {date of creation)|(for deletion, if no valid AD/Mailbox enabled)',
    • 'assign' => 'Homedirectory was reset to standard priviledges 2016-02-23',
    • 'delete' => 'Homedirectory was deleted 2016-02-23',
    • 'create' => 'Homedirectory was created 2016-02-23',
    • 'recreate' => 'Homedirectory was recreated with standard dir-template 2016-02-23'

HTTP verb URI Body Beschreibung
POST /user/[nethz username]/service/HomeDirectory   gibt ein "Service granted" zurück, falls der Service erfolgreich erteilt wurde
DELETE /user/[nethz username]/service/HomeDirectory   gibt ein "Service revoked" zurück, falls der Service erfolgreich entzogen wurde
GET /service/HomeDirectory?homeDirectoryStatus=delete*
[
    {
        "gidNumber": "174156",
        "nuid": "4967098",
        "npid": "65464",
        "description" : "testkonto",
        "uidNumber": "157539",
        "HomeDirectory": {
            "login_until": "31-DEC-9999",
            "service_name": "HomeDirectory",
            "cre_date": "26-JAN-2016",
            "delete_after": "31-DEC-9999",
            "homeDirectoryStatus": "delete homeDirectory",
            "enabled": "1"
        },
        "username": "nachtvogel"
    }
]
alle User zurückgeben, deren Directories gelöscht werden sollten
GET /service/HomeDirectory?homeDirectoryStatus=create* (wie oben) alle User ausfindig machen, für welche ein homeDirectory erstellt werden muss
GET /service/HomeDirectory?homeDirectoryStatus=recreate* (wie oben) alle User ausfindig machen, für welche das homeDirectory erneut erstellt werden muss
PUT /user/[nethz_username]/service/HomeDirectory { "homeDirectoryStatus" : "homeDirectory created" } Bestätigung schreiben, dass HomeDirectory erstellt wurde
PUT /user/[nethz_username]/service/HomeDirectory { "homeDirectoryStatus" : "homeDirectory deleted" } Bestätigung schreiben, dass HomeDirectory gelöscht wurde

PolyBox-Service

Um PolyBox nutzen zu können, benötigt man einen Account im LDAPS (nethz Service) sowie ein LDAPS-Attribut polyBoxQuota, welches die vorhandene Quota für diesen User anzeigt. Typischerweise sind dies 50GB. Das eigentliche Konto wird erst beim ersten Login generiert. Wenn die Person die ETH verlässt, soll in den Service-Metainformationen die Information gespeichert werden, wann die Löschung beauftragt wurde. Auf Seite von Polybox kann mit einem einfachem GET Request die Menge aller zu löschenden Kontos herausgefunden werden (siehe Tabelle). Ist die Löschung erfolgreich erfolgt, wird die Service Meta-Information entweder gelöscht (PUT und {} im Body) oder entsprechend aktualisiert.

HTTP verb URI Body Beschreibung
POST /user/[nethz username]/service/PolyBox   gibt ein "Service granted" zurück, falls der Service erfolgreich erteilt wurde
PUT /user/[nethz_username]/service/PolyBox { "polyBoxStatus" : "account created 2016-02-01" } Bestätigung schreiben, dass Polybox erstellt wurde
GET /service/PolyBox?polyBoxStatus=account created*
[
    {
        "gidNumber": "174156",
        "nuid": "4967098",
        "uidNumber": "157539",
        "Polybox": {
            "login_until": "31-DEC-9999",
            "service_name": "PolyBox",
            "cre_date": "26-JAN-2016",
            "delete_after": "31-DEC-9999",
            "polyBoxQuota" : "50 GB",
            "polyBoxStatus": "account created 2016-02-01",
            "enabled": "1"
        },
        "username": "nachtvogel"
    }
]
alle User zurückgeben, denen ein Account erstellt wurde
GET /service/PolyBox?polyBoxStatus=create* (wie oben) alle User ausfindig machen, für welche eine Polybox erstellt werden muss
GET /service/PolyBox?polyBoxStatus=recreate* (wie oben) alle User ausfindig machen, für welche die Polybox erneut erstellt werden muss
DELETE /user/[nethz username]/service/Polybox   gibt ein "Service revoked" zurück, falls der Service erfolgreich entzogen wurde
PUT /user/[nethz_username]/service/PolyBox { "polyBoxQuota" : "60 GB" } neue Quota setzen
PUT /user/[nethz_username]/service/PolyBox { "polyBoxStatus" : "account deleted 2016-02-01" } Bestätigung schreiben, dass Polybox gelöscht wurde

HPC-Service

Ein HPC-Account wird beim ersten Login erstellt. Zu diesem Zeitpunkt sollte auch dieser Webservice aufgerufen werden, damit der Service erstellt wird.

HTTP verb URI Body Beschreibung
POST /user/[nethz username]/service/HPC { "hpcStatus" : "account created 2016-02-01" } gibt ein "Service granted" zurück, falls der Service erfolgreich erteilt wurde. Ohne Body wird hpcStatus=create account 2016-02-01 gesetzt
DELETE /user/[nethz username]/service/HPC   gibt ein "Service revoked" zurück, falls der Service erfolgreich entzogen wurde
GET /service/HPC?hpcStatus=delete*
[
    {
        "gidNumber": "174156",
        "nuid": "4967098",
        "uidNumber": "157539",
        "HPC": {
            "hpcStatus": "delete account on 2016-02-30",
        },
        "username": "nachtvogel"
    }
]
alle User zurückgeben, deren HPC-Accounts gelöscht werden sollten
GET /service/HPC?hpcStatus=delete* (wie oben) alle User ausfindig machen, für welche der HPC-Account gelöscht werden soll
GET /service/HPC?hpcStatus=recreate* (wie oben) alle User ausfindig machen, für welche der HPC-Account erneut erstellt werden muss
PUT /user/[nethz_username]/service/HPC { "hpcStatus" : "account created on 2016-02-01" } Bestätigung schreiben, dass HPC-Account erstellt wurde
PUT /user/[nethz_username]/service/HPC { "hpcStatus" : "account deleted on 2016-02-01" } Bestätigung schreiben, dass HPC-Account gelöscht wurde

groupmgr — Gruppenmanagement

  • Die Pfade beziehen sich immer relativ zur Base-URI
    • Base-URI https://idn.ethz.ch/groupmgr
    • /cgi-bin/groupmgr/public/nethz (deprecated, langsam)
  • Das Format des Body ist immer JSON
  • die HTTP-Verben GET, POST, PUT, DELETE entsprechen den Operationen SELECT, CREATE, UPDATE, DELETE
  • bei POST-Requests ist darauf zu achten, dass der Header Content-type : application/json; charset=utf-8 mitgegeben wird. Nur so kann sichergestellt werden, wie die übermittelten Daten zu interpretieren sind.
  • die POST-Request benötigen eine Basic Authentication, d.h. Username/Passwort eines berechtigten Administrator-Accounts

Gruppeninformationen auslesen

HTTP verb URI Body Beschreibung Auth?
GET /group/hello-world-group
{
    "name" : "hello-world-group",
    "description" : "Hello World!",
    "admingroup" : "Entwurmer",
    "cre_date": "2014-06-12 15:48:31",
    "cre_by": "NPID=66083 (Swen Vermeul) UNAME=vermeul",
    "mod_date": "2016-03-23 23:15:13",
    "mod_by": "NPID=66083 (Swen Vermeul) UNAME=vermeul",
    "gid": 12345,
    "members" : [
        "user1",
        "user2",
        "untergruppe1"
    ]
    "targets": [
        "AD",
        "LDAPS"
    ],
}
Gruppeninformation einer einzelnen Gruppe -
GET /groups?agroup=meine-Admingruppe
[
   {
      "name" : "gruppe1",
      "admingroup" : "meine-Admingruppe",
      ...
   }
   {
      *name" : "gruppe2",
      ...
   }
]
Gruppeninformationen für alle Gruppen einer Admingruppe -
GET /groups?agroup=Entwurmer&name=group*
[
   {
      "name" : "group1",
      "description" : "ID Mail/Directories",
      "members" : [
         "areto",
         "carmena",
         "dakoch",
         "davidmcl",
         "fumathia",
         "furreran",
         "magoct",
         "manserd",
         "mueandre",
         "schmidlp",
         "sgoethal"
      ],
      "targets" : [
         "CQ5",
         "LDAPS",
         "AD"
      ]
   },
   {
      "name" : "group2",
      "description" : "ID Identity / Access Management & eServ",
      "members" : [
         "farnungc",
         "fcroci",
         "glange",
         "kdavor",
         "meierret",
         "mruepp",
         "spamin",
         "vermeul"
      ],
      "targets" : [
         "CQ5",
         "LDAPS",
         "AD"
      ]
   }
]
Gruppeninformationen mehrerer Gruppen anzeigen. Mit &search_mode=case_sensitive wird die Gross-/Kleinschreibung beachtet. -
GET /groups?name=groupname-starts-with*&search_mode=case_sensitive (s.o.) Gross-/Kleinschreibung beachten
GET /groupmgr/groups?gidNumber=12345 (s.o.) Gruppe anhand der gidNumber ausfindig machen. Achtung! Es existieren im Active Directory einige Gruppen, die nicht in nethz vorhanden sind aber dennoch eine gidNumber aufweisen. Sie werden von diesem Webservice nicht gefunden.
GET /group/group1/members
[
   "user1",
   "user2",
   "untergruppe1"
]
nur Gruppenmitglieder auslesen -
GET /user/[username]
[
    {
        "gidNumber": "8241",
        "descripton": "T-ID Software Services",
        "grid": "3036478",
        "name": "T0076",
        "type": "LZ"
    },
    {
        "gidNumber": "8614",
        "descripton": "T-ETH Zürich",
        "grid": "4113870",
        "name": "T0002",
        "type": "LZ"
    },
    {
        "gidNumber": "23769",
        "descripton": "Netzwerk Supportgruppen",
        "grid": "4132370",
        "name": "All_netsup",
        "type": "ISG"
    }
]
Alle Gruppen (auch übergeordnete) eines Users anzeigen -

Gruppen erstellen und modifizieren

HTTP verb URI Body Beschreibung Auth?
POST /group
{
    "name" : "ENTW-Hello",
    "description" : "World!",
    "admingroup" : "Entwurmer",
    "members" : [
        "user1",
        "user2",
        "untergruppe1"
    ]
    "targets": [
        "AD",
        "LDAPS"
    ],
}
neue Gruppe erstellen  
PUT /group/my_old_name
{
    "name" : "my_new_name",
    "description" : "Hello brave new World!"
}
Beschreibung oder Name der Gruppe my_new_name aktualisieren DONE
DELETE /group/my_obsolete_group   Gruppe my_obsolete_group definitiv löschen DONE

Mitglieder einer Gruppe

HTTP verb URI Body Beschreibung Auth?
POST / PUT /group/group1/members
[
    "user1",
    "subgroup2"
]
Gruppenmitglieder für Gruppe group1 setzen (User oder Untergruppen) DONE
POST / PUT /group/group1/members/add
[
    "user2",
    "subgroup3"
]
Gruppenmitglieder für Gruppe group1 hinzufügen (User oder Untergruppen) DONE
POST / PUT /group/group1/members/add_forgiving
[
    "possibly_unknown_user",
    "nonexisting_subgroup"
]
Gruppenmitglieder für Gruppe group1 hinzufügen (User oder Untergruppen), produziert nur Warnungen und keine Fehler DONE
POST / PUT /group/group1/members/del
[
    "user1",
    "subgroup2"
]
Gruppenmitglieder aus Gruppe group1 entfernen (User oder Untergruppen) DONE
DELETE /group/group5/members   alle Gruppenmitglieder aus der Gruppe group5 löschen DONE

Zielsysteme (Target Systems) einer Gruppe ändern.

HTTP verb URI Body Beschreibung Auth?
POST / PUT /group/group1/targets
[
    "AD",
    "LDAPS"
]
Gruppe group1 soll in die Zielsysteme AD und LDAPS exportiert werden (Setzen) DONE
POST / PUT /group/group1/targets/add
[
    "CQ5"
]
Gruppe group1 soll zusätzlich auch noch nach CQ5 exportiert werden (add) DONE
POST / PUT /group/group1/targets/del
[
    "AD",
]
Gruppe group1 soll nicht mehr ins Zielsysteme AD exportiert werden (del) DONE
DELETE /group/group2/targets   alle Zielsysteme für die Gruppe group2 löschen DONE
POST /group/group1/start_provisioning_targets
[
    "LDAPS",
    "AD"
]
Provisionierungen der Targetsysteme (LDAPS und AD) für group1 jetzt ausführen. Wenn kein Body mitgegeben wird, werden alle Target-Systeme provisioniert. DONE

nethz Prepay (Micropayment-System der ETH)

  • alle Return-Werte immer in JSON
  • die Verbindung ist immer https (wird vom Webserver so gesteuert)
  • alle Verbindungen sind mit Basic Authentication gesichert
  • Base-URI: https://idn.ethz.ch/prepay

HTTP verb URI Request Body Response Body Beschreibung
DONE GET /user/[username]  
{
   "firstname" : "Surname",
   "familyname" : "Given Name",
   "title" : "Frau Dr. Prof",
   "username" : "username",
   "uid_number" : 76543,
   "gid_number" : 5675,
   "npid" : "123456",
   "persid" : "98877656",
   "amount_available" : "17.05",
}
gibt für einen bestimmten User Detailinformationen zurück inklusive verfügbarer Prepay-Betrag
DONE GET /service/[servicename]  
{
    "service_name": "raplab",
    "description": "Labor für 3D-Druck auf dem Hönggerberg",
    "special_user": "123456",
    "modules_dir": null,
    "csid": "2"
}
gibt für einen bestimmten Service Detailinformationen zurück
DONE POST /service/[servicename]/user/[student_username]
{
    "amount" : "13.50",
    "payment_comment" : "Mein grossartiger 3D Ausdruck",
    "overdraw_limit" : "10.00"
}
{
    "amount_transferred" : "13.50",
    "account_balance" : "-3.50",
    "debitor": "student_username",
    "payment_comment": "raplab: Mein grossartiger 3D Ausdruck",
    "payment_date": "2016-06-14 17:22:10",
    "actor": "raplab",
    "creditor": "raplab"
}
Als Service-Provider einen Betrag für eine bezogene Leistung einkassieren

maillist.cgi — Maillisten-Administration

Anzeigen, modifizieren und löschen von Maillisten. Im Gegensatz zur Gruppenadministration können mit diesem Webservice vor allem Exchange-Mailverteiler modifiziert werden.

Parameter

  • list_name Name oder E-Mailadresse der Mailliste
  • admin_username, admin_pw optional, wird nur beim Modifizieren von Maillisten benötigt
  • action optional
    • action=delete Liste löschen
    • action=modify Listenmitglieder ändern
    • add ein Mitglied hinzufügen: add=username, add=name@domain, add=listenname, add=listname@domain
    • del ein Mitglied entfernen: del=username, del=name@domain, del=listenname, del=listname@domain
  • format Output-Format. Folgende Werte sind erlaubt: dumper, xml, json. Default ist json.
  • attr Attribut der Member, welches anstelle der dn ausgegeben werden soll (z.B. mail)
  • es kann anstatt Username oder Listenname immer auch die E-Mailadresse verwendet werden

nethz_service.cgi — nethz Services verwalten

  • admin_username Username des Administrators
  • admin_password Supernethz-Passwort dieses Administrators
  • username Username, bei welchem ein Serivce hinzugefügt / entfernt werden soll
  • service_name Name des Services
  • action=[grant|revoke] gibt an ob der Service dem User erteilt oder entzogen werden soll
  • sp_name_N Name des Service-Parameters (N ist der Zähler)
  • sp_value_N Wert des Service-Parameters
  • parameter_list gibt die möglichen Service-Parameter für einen Service aus: nethz_service.cgi?service_name=Mailbox¶meter_list

mobile_service.cgi — Registrierung des CMN-Services

  • password Passwort zum Schutz dieses Web-Services
  • username Username, wem der Service erteilt werden soll
  • grant_service erteilt User den Service
  • revoke_service entzieht User den Service
  • format Formatangabe für den Output
  • Fehlermeldungen werden mit dem HTTP-Statuscode 404 zurückgegeben.

read-only Webservices

SAP-Info

HTTP verb URI Body Beschreibung Bemerkungen
GET /sap_info/user/[username]
[
    {
        "bv_mail": "budgetverantwortlicher@ethz.ch",
        "beschr": "Institutsname",
        "finh": "username_fondsinhaber",
        "bvs": "username_budgetverantwortlicher_stv",
        "finh_mail": "fondsinhaber@ethz.ch",
        "bv": "username_budgetverantwortlicher",
        "bvs_name": "Name Stellvertreter Budgetverantwortlicher",
        "bvs_mail": "budget_stv@ethz.ch,
        "kostl": "9999",
        "bv_name": "Name Budgetverantwortlicher",
        "fonds": "FF0000-001",
        "finh_name": "Name Fondsinhaber"
    }
]
SAP-Informationen für einen bestimmten Usernamen. Nur der Budgetverantwortliche ist zwingend vorhanden. Die Werte für Stellvertreter (bvs) sowie Fondsinhaber (finh) können null sein. Bei mehreren Anstellungen werden mehrere Kostenstellen und Fondsnummern ausgegeben.
GET /sap_info/kostl/9999 Output wie oben    
GET /sap_info?kostl=9999 Ouptut wie oben    
GET /sap_info?bv=username_budgetverantwortlicher Ouptut wie oben, eventuell auch mehr, falls der Budgetverantwortliche für mehrere Fondsnummern verantwortlich ist.    

adgroup — Gruppen im AD

  • unter http://webservice.ethz.ch/cgi-bin/adgroup abrufbar
  • nur Hosts innerhalb der ETH sind zugelassen
  • Gruppennamen werden standardmässig klein geschrieben ausgegeben
  • Parameter: case_sensitivity
    • lowercase (Standard, alle Gruppen werden kleingeschrieben ausgegeben, ist aber nicht empfohlen)
    • mixed (Gruppen werden in Original-Schreibweise ausgegeben
  • Ausgabe-Format: groupname:*:GUID
  • Beispiel: testgruppe:*:123456
  • Konfigurationsdatei ist unter ~/conf/ad.conf zu finden

adgroup2 — Gruppen im AD

  • unter http://webservice.ethz.ch/cgi-bin/adgroup2 abrufbar
  • nur spezifische Hosts innerhalb der ETH sind zugelassen
  • Gruppennamen werden immer in Gross- und Kleinschreibung ausgegeben
  • Parameter: keine
  • Ausgabe-Format: groupname:*:GUID
  • Beispiel: TestGruppe:*:123456
  • allowed_hosts enthält die Liste der zugelassenen Hosts
  • Konfigurationsdatei ist unter ~/conf/ad.conf zu finden

adpasswd — User im AD

  • ohne Parameter
  • unter http://webservice.ethz.ch/cgi-bin/adpasswd abrufbar
  • Format: username.d:*:UUID:PRIMARY_GUID:*:*:*
  • Beispiel: swen.d:*:1234:5678:*:*:*
  • Username immer kleingeschrieben
  • die primäre Gruppe eines Users kann im Mailbox-Tool innerhalb vom Admin-Tool angepasst werden
  • die GUID = 1029 steht für die allgemeine Gruppe «Domain Users», sie ist die Standard-Gruppe für alle User im AD
  • allowed_hosts enthält die Liste der zugelassenen Hosts
  • Konfigurationsdatei ist unter ~/conf/ad.conf zu finden

adpasswd2 — User im AD

  • ohne Parameter
  • unter http://webservice.ethz.ch/cgi-bin/adpasswd2 abrufbar
  • Format: username.d:*:UUID:PRIMARY_GUID:*:*:*
  • Beispiel: swen.d:*:1234:5678:*:*:*
  • Username Gross und kleingeschrieben
  • die primäre Gruppe eines Users kann im Mailbox-Tool innerhalb vom Admin-Tool angepasst werden
  • die GUID = 1029 steht für die allgemeine Gruppe «Domain Users», sie ist die Standard-Gruppe für alle User im AD
  • allowed_hosts enthält die Liste der zugelassenen Hosts
  • Konfigurationsdatei ist unter ~/conf/ad.conf zu finden

group_info.cgi — Gruppen-Informationen

Gibt Informationen über die in nethz gespeicherten Gruppen (Ngroups) aus. Wird vom Multimedia-Portal verwendet.

  • grid (Primärschlüssel der Gruppe)
  • group_type
  • name
  • description

Parameter

  • group_type (lz, student,custom)
  • format (xml, dumper, json*)

get_machine_info.cgi — Maschinen-Info (vorerst vor allem für Netbackup)

Parameter (mindestens einer ist notwendig)

  • service Name des Service, welcher an diese Maschine gekoppelt ist (z.B. "Netbackup" oder "System")
  • username verantwortlicher User
  • group_name verantwortliche Gruppe
  • machine_name Name der Maschine

URL https://idn.ethz.ch/cgi-bin/admin_tool/get_machine_info.cgi?service=Netbackup

get_info_for_username.cgi — Username-Info

Beschreibung Gibt für einen oder mehrere nethz Usernamen Informationen über die ETH-Zugehörigkeit zurück. Das Ausgabeformat ist entweder Data::Dumper (default), XML oder JSON.

URL https://idn.ethz.ch/cgi-bin/admin_tool/get_info_for_username.cgi

Parameter

  • username nethz Username
  • der Parameter kann mehrmals vorkommen, dann werden mehrere Ergebnisse gleichzeitig dargestellt
  • format Output-Format. Mögliche Werte sind dumper (Standard), xml oder json

Output

Ohne spezifischen format Parameter wird ein Perl Data::Dumper Format ausgegeben:

$VAR1 = [
          {
            'Mitarbeiter' => [
                               {
                                 'bis' => '31-DEC-9999',
                                 'leitzahl' => '06065',
                                 'persid' => '55327',
                                 'pnr' => '00033018',
                                 'von' => '01-JAN-2011'
                               }
                             ],
            'email' => 'swen@ethz.ch',
            'npid' => '66083',
            'nuid' => '69903',
            'other_usernames' => [
                                   'aus',
                                   'servicecenter'
                                 ],
            'services' => {
                            'Administrator' => {
                                                 'delete_after' => '31-DEC-9999',
                                                 'login_until' => '31-DEC-9999'
                                               },
                            'Alarm' => {
                                         'delete_after' => '31-DEC-9999',
                                         'login_until' => '31-DEC-9999'
                                       },
                            'Bibliothek' => {
                                              'delete_after' => '31-DEC-9999',
                                              'login_until' => '31-DEC-9999'
                                            },
                            'Credit' => {
                                          'delete_after' => '31-DEC-9999',
                                          'login_until' => '31-DEC-9999'
                                        },
                            'ISG-Root' => {
                                            'delete_after' => '31-DEC-9999',
                                            'login_until' => '31-DEC-9999'
                                          },
                            'Inventar-DB' => {
                                               'delete_after' => '31-DEC-9999',
                                               'login_until' => '31-DEC-9999'
                                             },
                            'Mac' => {
                                       'delete_after' => '31-DEC-9999',
                                       'login_until' => '31-DEC-9999'
                                     },
                            'Mailbox' => {
                                           'delete_after' => '31-DEC-9999',
                                           'login_until' => '31-DEC-9999'
                                         },
                            'Mitarbeiter-IDES' => {
                                                    'delete_after' => '31-DEC-9999',
                                                    'login_until' => '31-DEC-9999'
                                                  },
                            'Mitarbeiter-Listen' => {
                                                      'delete_after' => '31-DEC-9999',
                                                      'login_until' => '31-DEC-9999'
                                                    },
                            'NAS-DFS' => {
                                           'delete_after' => '31-DEC-9999',
                                           'login_until' => '31-DEC-9999'
                                         },
                            'Nethz' => {
                                         'delete_after' => '31-DEC-9999',
                                         'login_until' => '31-DEC-9999'
                                       },
                            'Phone' => {
                                         'delete_after' => '31-DEC-9999',
                                         'login_until' => '31-DEC-9999'
                                       },
                            'PolyPhone' => {
                                             'delete_after' => '31-DEC-9999',
                                             'login_until' => '31-DEC-9999'
                                           },
                            'Root' => {
                                        'delete_after' => '31-DEC-9999',
                                        'login_until' => '31-DEC-9999'
                                      },
                            'Studentenlisten' => {
                                                   'delete_after' => '31-DEC-9999',
                                                   'login_until' => '31-DEC-9999'
                                                 },
                            'VPN' => {
                                       'delete_after' => '31-DEC-9999',
                                       'login_until' => '31-DEC-9999'
                                     }
                          },
            'username' => 'vermeul'
          }
        ];

Mit form=xml wird ein XML ausgegeben:

<opt email="swen@ethz.ch" npid="66083" nuid="69903" username="vermeul">
  <Mitarbeiter bis="31-DEC-9999" leitzahl="06065" persid="55327" pnr="00033018" von="01-JAN-2011" />
  <other_usernames>aus</other_usernames>
  <other_usernames>off</other_usernames>
  <other_usernames>servicecenter</other_usernames>
</opt>

mit form=json werden die Daten im JSON-Format (Java-Script Object Notation) wiedergegeben:

[{"email":"swen@ethz.ch","other_usernames":["aus","servicecenter"],"services":{"Bibliothek":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Mac":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Alarm":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Nethz":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Mitarbeiter-IDES":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Administrator":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Root":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Studentenlisten":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"PolyPhone":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"ISG-Root":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Mailbox":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Phone":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Mitarbeiter-Listen":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Credit":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"NAS-DFS":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"VPN":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"},"Inventar-DB":{"login_until":"31-DEC-9999","delete_after":"31-DEC-9999"}},"nuid":"69903","npid":"66083","Mitarbeiter":[{"leitzahl":"06065","bis":"31-DEC-9999","persid":"55327","pnr":"00033018","von":"01-JAN-2011"}],"username":"vermeul"}]

Eine Person kann mehrere Beziehungen zur ETH haben. Folgende Personen-Kategorien werden unterschieden:

  • Mitarbeiter
  • Dozent
  • Student
  • Gast
  • Emeritus
  • ETH-nahe
  • Hörer

ethbib_info.cgi — Daten für die ETH-Bibliothek

Beschreibung Datenbank-Auszug aller Mitarbeiter, Dozenten und Studierenden (Personendaten, Büro- und Heimadresse) für den Import ins System ALEPH. Die zugelassenen Maschinen sind direkt im Skript vermerkt.

60 Tage nach dem definitiven Austritt aus der ETH (Anstellungsende/Exmatrikulation/Ende Dozentenperiode/Ende Gastperiode) wird im Feld BEZIEHUNGEN der Wert «AUSTRITT: YYYY-MM-DD» (Jahr-Monat-Tag) geliefert. Der automatisierte Abgleich mit dem ALEPH-System muss dabei sicherstellen, dass Leute mit Spezialkonditionen separat behandelt und nicht sofort in Privatkunden umgewandelt werden.

Parameter

  • charset=iso-8859-1 gibt die Daten ISO-8859-1 (Latin-1) encodiert zurück. Standardmässig wird UTF-8 ausgegeben.
  • headers=true zeigt die Tabellenüberschriften an

Felder, die zurückgegeben werden

  • persid Identifikationsnummer der PDB
  • firstname
  • familyname
  • gender
  • date_of_birth
  • username nethz Username
  • unique_id npid@ethz.ch - Personen-Identifikationsnummer von nethz, analog zum Attribut swissEduPersonUniqueID im LDAPS/AAI
  • ethicscode Bibliotheks-Code, wie auf der ETH-Karte ersichtlich
  • mail
  • mobile zertifizierte Mobile-Nummer
  • off_adrzeil1 erste Büro-Adresse (nach Prioritäten-Algorithmus)
  • off_adrzeil2
  • off_adrzeil3
  • off_adrplz
  • off_adrort
  • off_adrland
  • off_adrtel
  • home_adrzeil1 erste Heimadresse (nach Prioritäten-Algorithmus)
  • home_adrzeil2
  • home_adrzeil3
  • home_adrplz
  • home_adrort
  • home_adrland
  • home_adrtel
  • hoerer Hörer-Status. Wert 80 bedeutet «Doktorand».
  • aw_gueltig_bis Datum, bis wann die ETH-Karte gültig ist. Wird regelmässig nachgeführt.
  • beziehungen Durch $ getrennte Werte wie Mitarbeiter$Student$Dozent$Emeritus$ETH-nahe etc. Falls keine ETH-Beziehung mehr vorhanden ist, wird 60 Tage nach Austritt der String Austritt: YYYY-MM-YY ausgegeben

Deprecated

Webservices, welche aus verschiedenen Gründen veraltet sind

credit_transaction.cgi — Prepaid-Service Buchungen (Micropayment) DEPRECATED

  • admin_username Username des Service-Owners, auf dessen Konto das Geld überwiesen wird
  • admin_password Passwort für diesen User
  • username Username des Kunden, bei welchem ein Betrag abgebucht werden soll
  • service_name Name der Dienstleistung
  • get_amount_available (optional) gibt den Betrag zurück, welcher auf dem Konto des Users noch vorhanden ist.
  • amount (optional) Betrag in CHF, Dezimaltrennzeichen ist der Punkt .
  • payment_comment (muss-Feld, falls amount) Text für die Transaktion
  • format (optional). Gibt den Output im xml, dumper oder json-Format aus. Standardmässig wird json verwendet.

authev.cgi — Authentisierung für Evento DEPRECATED

  • DEPRECATED: dieser Web-Service gilt als veraltet und wird bei der anstehenden Shibbolisierung von Evento abgeschafft (hoffentlich noch in diesem Jahrhundert)
  • URL: https://idn.ethz.ch/cgi-bin/auth/authev.cgi?appid=evento&login=nethz_username&pass=nethz_password
  • gibt einen String in folgendem Format zurück:
  • NPID:nethz_username:mail:Vorname:Nachname:Post-Zeile1:Post-Zeile2:Land:Postleitzahl:Ort:Personenkategorie Leitzahl:Anrede
  • 66083:vermeul:swen@ethz.ch:Swen:Vermeul:ID Software Services:Weinbergstrasse 11:ETH Zürich, WEC E 15:CH :8092:Zürich:Mitarbeiter 06065:Herr

statistics.pl — Statistiken für nethz-Applikationen DEPRECATED

  • gibt aktuelle Kennzahlen einiger bekannter nethz-Applikationen zurück
  • nethz Admin-Tool
  • Inventar-Datenbank
  • Alarm-Tool
  • SMS-Gateway

get_info_for_lz.cgi — Infos für Organisationseinheiten erhalten. DEPRECATED

  • lz=06065 gibt alle Informationen über die angegebene Leitzahl zurück
  • lz=T0070 gibt alle Informationen über die angegebene Totalisierungsleitzahl zurück
  • format=json Standardmässig werden die Daten im JSON-Format ausgegeben. Möglich sind auch xml oder dumper.

-- SwenVermeul - 2012-03-15

Topic revision: r94 - 2017-09-12 - SwenVermeul
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback