Authenticate using the Command Line Interface (CLI)

Authentication is required for creating or updating content and also for accessing authorised content which is not publically available. The credentials need to be first created using keycloak. To authenticate using the command line interface, some additional scripts needs to be run to get the token from the keycloak interface, which then needs to be used with each REST-API call with the repositories.

1. Open command prompt

2. Create a new file called enviroment.sh in a folder of your choice. For this, type
   cat > environment.sh in the command line and press enter. Now the content of this file needs to be written as per the code snippet below. This can be done by replacing <account_name> and <password> with your actual account name and password in the following code segment and typing(or copying) it to the command prompt. Then click Ctrl+D, to save and close the file. If the file exists already, the <account_name> and <password> need to be replaced with that of the current user using a command line based file editor like “nano” or “Vim”.

    METASTOREHOST="matwerk.datamanager.kit.edu:8040"
    BRHOST="matwerk.datamanager.kit.edu:8090"
    KEYCLOAKUSERNAME="<account_name>"
    KEYCLOAKPASSWORD="<password>"
   
   

3. In the same folder, create another script file called get_token.sh. By executing this script, a token will be obtained from keycloak which will be valid for the next 5 minutes. This token should be used with the REST-API calls to authenticate the usage. When five minutes are over, a new token needs to be generated. Else an error 401 or 403 will be obtained which correspond to forbidden or unauthorised access.

   First type cat > get_token.sh in the command prompt and press enter.

   Copy the following code segment inside the file and press Ctrl+D, to save the file get_token.sh.

    source environment.sh
    curl --location --request POST 'https://gateway.datamanager.kit.edu:8443/realms/nfdi4matwerk/protocol/openid-connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=kitdm-services' \
    --data-urlencode 'username='${KEYCLOAKUSERNAME}'' \
    --data-urlencode 'password='${KEYCLOAKPASSWORD}'' \
    --data-urlencode 'grant_type=password' -s | jq  -r '.access_token'
   
   

4. Make both environment.sh and get_token.sh executable scripts with chmod. This step is only needed for Mac and Linux, as Windows would treat the scripts as executables without additional action. For making the scripts executable, type chmod +x environment.sh get_token.sh and press enter. Steps 3 and 4 need to be done only once in a new environment.

Using the Token

1. Type TOKEN=$(./get_token.sh) in the command line and press enter. This will save the access token in a variable called “TOKEN” by executing the script get_token.sh. After expiry of the current token, the line TOKEN=$(./get_token.sh) has to be executed to generate a new token.

2. In all the code segments which require authentication, add the segment --oauth2-bearer ${TOKEN} after the URL to use the generated access token. For example to access a particular data resource with UID 3035cf01-cb70-4fb7-9a3a-ef5b4fb99da0, the command has to be modified to
   curl 'https://matwerk.datamanager.kit.edu/api/v1/dataresources/3035cf01-cb70-4fb7-9a3a-ef5b4fb99da0' --oauth2-bearer ${TOKEN} -i -X GET
   or
   curl 'https://matwerk.datamanager.kit.edu/api/v1/dataresources/3035cf01-cb70-4fb7-9a3a-ef5b4fb99da0' --oauth2-bearer ${TOKEN} -s | jq

3. Anytime an error message as unauthorised or forbidden access is encountered, check whether five minutes are over since the creation of the token. If yes, repeat step 1 to create a new token and continue with the required REST-API calls.