Rather than user names and passwords being maintained by HSDS, Keycloak ("https://www.keycloak.org/") can be used for authentication. In this mode, the client will fetch atoken from the Keycloak service that it then passes to the server as an HTTP request with a "Bearer" authorization header. From this token the server can validate the token and determine the username. The token is valid for a specific period (typically an hour), so the client will not need to fetch a new token on each request.
Once a client request is authenticated, the requested action still needs to be authorized by the server based on the ACLs for the given folder or domain. For example, for user [email protected] to create a domain /home/joebob/foo.h5, the folder /home/joebob/ will need to provide write permissions for [email protected]. This can be done using the h5pyd hsacl tool. For example: $ hsacl /home/joebob/ +crudep [email protected].
Keycloak authentication can be used in combination with accounts managed by the server. If HTTP Basic Auth is used in the client request, the username and password will be validated against the local account (if any have been setup). If HTTP Bearer token is used, the request will be authenticated be decoding the token.
In the hsds/admin/config directory, create the file "override.yml" if it doesn't already exist.
In the override.yml file, create the following lines. Replace "server_dns" and "server_port" with the DNS name and port for the Keycloak server. Replace "keycloak_realm" with the Realm being used in Keycloak.
openid_provider: keycloak # Use "keycloak" as the authentication provider
openid_url: http://<server_dns>:<server_port>/auth/realms/<keycloak_realm>/.well-known/openid-configuration # update to use your Keycloak location and realm
openid_audience: account # OpenID audience. Keycloak client id.
openid_claims: preferred_username,appid # Comma seperated list of claims to resolve to usernames.
If you would like to use a Keycloak username as the server administrative account instead of "admin", add the following to override.yml:
admin_user: <admin_username> # user who will have admin privileges.
The admin_user override is required if using Keycloak authentication exclusively.
Save the file and then stop and start the server for the configuration changes to take effect.
If you are deploying on Kubernetes or OpenShift you'll need to delete and recreate the configmap objects (see the HSDS kubernetes install guide for your platform).
In the Keycloak Admin console, choose the realm being used with HSDS, the select the "Clients" tab. Click the the "create" button and enter a name for the client to be used with HSDS.
On each client machine(s), create a file ".hscfg" in the user's home folder with the following lines (updated for your particular configuration):
hs_endpoint = http://hsds.hdf.test # endpoint for HSDS
hs_username = my_username # username
hs_password = my_password # password
hs_keycloak_uri = http://keycloak.acme.org:8080 # endpoint for Keycloak
hs_keycloak_client_id = myclient # client id
hs_keycloak_realm = myrealm # realm on Keycloak
hs_api_key = # leave this empty
Test by running: $hstouch /home/<username>/foo.h5 where /home/<username>/ has the approriate ACL as explained in the introduction.
You will be prompted to enter a code to authenticate via Active Directory.
Note: Rather than modifying the .hscfg file, you can use environment variables instead. For example, for the client id, use the following command: export HS_KEYCLOAK_CLIENT_ID=my_client.