HBP HPC LDAP server

The HBP HPC LDAP server is hosted by JSC. The server provides both LDAP protocol and REST API access to the central HBP HPC LDAP server.

Connection points

Protocol	URL	Example call
LDAP	ldaps://hbpacc.zam.kfa-juelich.de:636	ldapsearch -v -W -H ldaps://hbpacc.zam.kfa-juelich.de:636 -D <LDAPBINDDN> -b "ou=users,dc=hbp,dc=eu" uid
REST	​https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/doc	curl -X GET --header 'Accept: application/json' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts'

Both protocols can be used for read and write access. The REST API is intended to be simpler to use, as it offers powerful dispatch commands, which combine multiple LDAP protocol operations in a single REST call. E.g. by calling the REST function https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts?oidcid=123&action=create&project=bp01 a bp0-account is created for the user with oidcid 123 within project bp01. To achieve that with plain LDAP protocol, the people entry for that person needs to be searched, imported into the users branch and the new account needs to be stored as member of the project entry.

Getting started

Every HPC site has its own service account, which can be used both for LDAP access and REST calls. E.g. for the JSC the LDAP bind DN is o=FZJ,ou=sites,dc=hbp,dc=eu and the username for the Rest API is FZJ. For both APIs the same password is used. After your first login, we recommend to change your password for the service account. You can do that with the following REST call:

curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/ldapaccess/serviceaccounts/FZJ?oldpassword=AAABBB&newpassword=cccddd&newpasswordrepeated=cccddd'

Note, that you need to replace FZJ with the name of your site, and the oldpassword parameter with your real password. Otherwise, the call will fail. We also recommend to use the Swagger UI at ​https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/doc to run this call, which is much simpler than calling the curl command. On the Swagger UI, login with your initial site account (FZJ,BSC, and so forth) and password. Then click on Administration followed by patch /ldapaccess/serviceaccounts/{site} . Fill in your credentials and your new password.

LDAP schema

The current LDAP schema is depicted in the following two diagrams:

Entity-Relationship model:

LDAP tree structure and connections:

Rest API example calls

The Rest API documentation can be found at ​https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/doc. You can use the Swagger UI to generate all REST API calls. Here are some example calls on this REST API:

Examples:

Projects

• get

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects
  

• add new project

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects?projectname=bp045678'
  

• get project details

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp045678
  

• add accounts to project

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp045678/accounts?bp0ID=bp000005'
  

• get accounts of project

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp045678/accounts
  

• remove account from project

  curl -X DELETE --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp045678/accounts/bp000005'
  

• add project to system

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp045678/systems?system=juqueen'
  

• delete project

  curl -X DELETE --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp045678'
  

Accounts

• get account list

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts
  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts?filter=cn%3D*Karbach*
  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts?filter=uid%3D*5
  

• create account for project

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts?oidcid=244515&action=create&project=bp02'
  

• get account details

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/accounts/bp000003
  

• add account to project

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp000001/accounts?bp0ID=bp000004'
  

• delete account from project

  curl -X DELETE --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/projects/bp000001/accounts/bp000004'
  

People

• get all stored OIDC IDs

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people
  

• get filtered by mail

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people?filter=mail%3D*karbach*
  

• get person details

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people/244515
  

• find person entries from OIDC server

  https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people/oidc?filter=sn%3DOrth
  

• import person entry from OIDC

  curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people?oidcid=255622'
  

• update attributes for person

  curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people/255622?attribute=postaladdress&action=add&value=Forschungszentrum%20Juelich%20GmbH%3BWilhelm-Johnen-Strasse%3B%3B52428%3BJuelich%3BGermany'
  

• delete person and all connected accounts

  curl -X DELETE --header 'Accept: text/html' 'https://hbpacc.zam.kfa-juelich.de/hpcmanagement/v1/people/255622'
  

Trouble shooting

Missing certificates for LDAP

If ldapsearch commands fail with the following error message:

ldap_start_tls: Can't contact LDAP server (-1)
        additional info: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed (self signed certificate in certificate chain)

Try to add the root certificate for our server certificate to the trusted certificates. The root certificate can be found at ​https://www.pki.dfn.de/fileadmin/PKI/zertifikate/deutsche-telekom-root-ca-2.pem Download that certificate, then do the following:

export LDAPTLS_CACERT=/path/to/certificate/deutsche-telekom-root-ca-2.pem
ldapsearch -v -W -H ldaps://hbpacc.zam.kfa-juelich.de:636 -D o=FZJ,ou=sites,dc=hbp,dc=eu -b "ou=users,dc=hbp,dc=eu" uid

Afterwards, the LDAP commands should work.