HTTP Basic Authentication

The default method for securing the Ralph API server is HTTP Basic Authentication. For this, we need to create a user in Ralph LRS.

Creating user credentials

To create a new user credentials, Ralph CLI provides a dedicated command:

Ralph CLIDocker Compose

ralph auth \
    --write-to-disk \
    --username janedoe \
    --password supersecret \
    --scope statements/write \
    --scope statements/read \
    --agent-ifi-mbox mailto:janedoe@example.com

docker compose run --rm lrs \
  ralph auth \
    --write-to-disk \
    --username janedoe \
    --password supersecret \
    --scope statements/write \
    --scope statements/read \
    --agent-ifi-mbox mailto:janedoe@example.com

Tip

You can either display the helper with ralph auth --help or check the CLI tutorial here

This command updates your credentials file with the new janedoe user. Here is the file that has been created by the ralph auth command:

auth.json

[                                                                               
  {                                                                             
    "agent": {                                                                  
      "mbox": "mailto:janedoe@example.com",                                     
      "objectType": "Agent",                                                    
      "name": null                                                              
    },                                                                          
    "scopes": [                                                                 
      "statements/write",                                                           
      "statements/read"
    ],                                                                          
    "hash": "$2b$12$eQmMF/7ALdNuksL4lkI.NuTibNjKLd0fw2Xe.FZqD0mNkgnnjLLPa",     
    "username": "janedoe"                                                       
  }                                                                             
] 

Alternatively, the credentials file can also be created manually. It is expected to be a valid JSON file. Its location is specified by the RALPH_AUTH_FILE configuration value.

Tip

By default, Ralph LRS looks for the auth.json file in the application directory (see click documentation for details).

The expected format is a list of entries (JSON objects) each containing:

• the username
• the user’s hashed+salted password
• the scopes they can access
• an agent object used to represent the user in the LRS.

Info

The agent is constrained by LRS specifications, and must use one of four valid Inverse Functional Identifiers.

Making a GET request

After changing the docker-compose.yml file as follow:

docker-compose.yml

version: "3.9"

services:

  lrs:
    image: fundocker/ralph:latest
    environment:
      RALPH_APP_DIR: /app/.ralph
      RALPH_RUNSERVER_BACKEND: fs
      RALPH_RUNSERVER_AUTH_BACKENDS: basic
    ports:
      - "8100:8100"
    command:
      - "uvicorn"
      - "ralph.api:app"
      - "--proxy-headers"
      - "--workers"
      - "1"
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "8100"
    volumes:
      - .ralph:/app/.ralph

and running the Ralph LRS with:

docker compose up -d lrs

we can request the whoami endpoint again, but this time sending our username and password through Basic Auth:

curlHTTPie

curl --user janedoe:supersecret http://localhost:8100/whoami

{"agent":{"mbox":"mailto:janedoe@example.com","objectType":"Agent","name":null},"scopes":["statements/read","statements/write"]}

http -a janedoe:supersecret :8100/whoami 

HTTP/1.1 200 OK
content-length: 107
content-type: application/json
date: Tue, 07 Nov 2023 17:32:31 GMT
server: uvicorn

{
    "agent": {
        "mbox": "mailto:janedoe@example.com",
        "name": null,
        "objectType": "Agent"
    },
    "scopes": [
        "statements/read",
        "statements/write"
    ]
}

Congrats! 🎉 You have been successfully authenticated!

HTTP Basic auth caching

HTTP Basic auth implementation uses the secure and standard bcrypt algorithm to hash/salt passwords before storing them. This implementation comes with a performance cost.

To speed up requests, credentials are stored in an LRU cache with a “Time To Live”.

To configure this cache, you can define the following environment variables:

• the maximum number of entries in the cache. Select a value greater than the maximum number of individual user credentials, for better performance. Defaults to 100.

RALPH_AUTH_CACHE_MAX_SIZE=100

- the “Time To Live” of the cache entries in seconds. Defaults to 3600s.

RALPH_AUTH_CACHE_TTL=3600