Update test docs

GETTING_STARTED.md

@@ -4,41 +4,233 @@ WARNING: This document is still in progress, and due to the high rate of change
 tooling, may be OUT OF DATE or otherwise incorrect. If you have questions, please get
 in contact!
 
-Create the service account
+The goal of this getting started is to give you a quick setup, and overview of how you can setup
+a working RADIUS environment with kanidm
 
+# Deploying with docker
+
+Currently we have a docker image based on git master. They can be found at:
+
+    https://hub.docker.com/r/firstyear/kanidmd
+    https://hub.docker.com/r/firstyear/kanidm_radius
+
+First we'll deploy the main server. You'll need a volume where you can put certificates and
+the database:
+
+    docker volume create kanidmd
+
+You should have a ca.pem, cert.pem and key.pem in your kanidmd volume. It's up to you to put them
+in there some how.
+
+Then you can setup the initial admin account and initialise the database into your volume.
+
+    docker run --rm -i -t -v kanidmd:/data firstyear/kanidmd:latest /home/kanidm/target/release/kanidmd recover_account -D /data/kanidm.db -n admin
+
+You can now run the server - note that we provide all the options on the cli, but this pattern
+may change in the future.
+
+    docker run -p 443:8443 -v /Users/william/development/rsidm/insecure:/data firstyear/kanidmd:latest /home/kanidm/target/release/kanidmd server -D /data/kanidm.db -C /data/ca.pem -c /data/cert.pem -k /data/key.pem --bindaddr 0.0.0.0:8443 --domain localhost
+
+# Using the cli
+
+For now, the CLI is still from the source - we'll make a tools container soon!
+
+After you check out the source, navigate to:
+
+    cd kanidm_tools
+    cargo build
+
+Now you can check your instance is working. You may need to provide a CA certificate for verification
+with the -C parameter:
+
+    cargo run -- self whoami -C ../path/to/ca.pem -H https://localhost --name anonymous
+    cargo run -- self whoami -H https://localhost --name anonymous
+
+Now you can take some time to look at what commands are available - things may still be rough so
+please ask for help at anytime.
+
+# Setting up some accounts and groups
+
+The system admin account (the account you recovered in the setup) has limited privileges - only to
+manage high-privilege accounts and services. This is to help seperate system administration
+from identity administration actions.
+
+You should generate a secure password for the idm_admin account now, by using the admin account to
+reset that credential.
+
+    cargo run -- account credential generate_password -H ... --name admin idm_admin
+    Generated password for idm_admin: tqoReZfz....
+
+It's a good idea to use the "generate_password" for high security accounts due to the strong
+passwords generated.
+
+We can now use the idm_admin to create groups and accounts.
+
+    cargo run -- group create radius_access_allowed -H ... --name idm_admin
+    cargo run -- account create demo_user "Demonstration User" -H ... --name idm_admin
+    cargo run -- group add_members radius_access_allowed demo_user -H ... --name idm_admin
+    cargo run -- group list_members radius_access_allowed -H ... --name idm_admin
+    cargo run -- account get demo_user -H ... --name idm_admin
+
+You can also use anonymous to view users and groups - note that you won't see as many fields due
+to the different anonymous access profile limits!
+
+    cargo run -- account get demo_user -H ... --name anonymous
+
+Finally, performa a password reset on the demo_user - we'll be using them from now to show how
+accounts can be self sufficent.
+
+    cargo run -- account credential set_password demo_user -H ... --name idm_admin
+    cargo run -- self whoami -H ... --name demo_user
+
+# RADIUS
+
+Let's make it so that demo_user can authenticate to our RADIUS. It's an important concept in kanidm
+that accounts can have *multiple* credentials, each with unique functions and claims (permissions)
+to limit their scope of access. An example of this is that an account has a distinction between
+the interactive (primary) credential and the RADIUS credentials.
+
+When you ran set_password above, you were resetting the primary credential of the account. The
+account can now *self manage* it's own RADIUS credential which is isolated from the primary
+credential. To demonstrate we can have the account self-generate a new RADIUS credential and
+then retrieve that when required.
+
+    cargo run -- account radius generate_secret demo_user -H ... --name demo_user
+    cargo run -- account radius show_secret demo_user -H ... --name demo_user
+    # Radius secret: lyjr-d8...
+
+To read these secrets, the radius server requires a service account. We can create this and
+assign it the appropriate privilege group (note we do this as admin not idm due to modifying a high priviliege group,
+which idm_admin is *not* allowed to do):
+
+    cargo run -- account create radius_service_account "Radius Service Account" -H ... --name admin
+    cargo run -- group add_members idm_radius_servers radius_service_account -H ... --name admin
+    cargo run -- account get radius_service_account -H ... --name admin
+    cargo run -- account credential generate_password radius_service_account -H ... --name admin
+
+Now that we have a user configured with RADIUS secrets, we can setup a radius container to authenticate
+with it. You will need a volume that contains:
+
+    data
+    data/ca.pem  # This is the kanidm ca.pem
+    data/config.ini
+    data/certs
+    data/certs/dh  # openssl dhparam -out ./dh 2048
+    data/certs/key.pem  # These are the radius ca/cert
+    data/certs/cert.pem
+    data/certs/ca.pem
+
+It's up to you to get a key/cert/ca for this purpose. The example config.ini looks like this:
+
+    [kanidm_client]
+    url =
+    strict = false
+    ca = /data/ca.crt
+    user =
+    secret =
+
+    ; default vlans for groups that don't specify one.
+    [DEFAULT]
+    vlan = 1
+
+    ; [group.test]
+    ; vlan =
+
+    [radiusd]
+    ca =
+    key =
+    cert =
+    dh =
+    required_group =
+
+    ; [client.localhost]
+    ; ipaddr =
+    ; secret =
+
+A fully configured example is:
+
+    [kanidm_client]
+    ; be sure to check the listening port is correct, it's the docker internal port
+    ; not the external one!
+    url = https://<kanidmd container name or ip>:8443
+    strict = true # adjust this if you have ca validation issues
+    ca = /data/ca.crt
+    user = radius_service_account
+    secret = # The generated password from above
+
+    ; default vlans for groups that don't specify one.
+    [DEFAULT]
+    vlan = 1
+
+    ; [group.test]
+    ; vlan =
+
+    [radiusd]
+    ca = /data/certs/ca.pem
+    key =  /data/certs/key.pem
+    cert = /data/certs/cert.pem
+    dh = /data/certs/dh
+    required_group = radius_access_allowed
+
+    [client.localhost]
+    ipaddr = 127.0.0.1
+    secret = testing123
+
+    [client.docker]
+    ipaddr = 172.17.0.0/16
+    secret = testing123
+
+Now we can launch the radius instance:
+
+    docker run --name radiusd -i -t -v ...:/data firstyear/kanidm_radius:latest
+    ...
+    Listening on auth address 127.0.0.1 port 18120 bound to server inner-tunnel
+    Listening on auth address * port 1812 bound to server default
+    Listening on acct address * port 1813 bound to server default
+    Listening on auth address :: port 1812 bound to server default
+    Listening on acct address :: port 1813 bound to server default
+    Listening on proxy address * port 53978
+    Listening on proxy address :: port 60435
+    Ready to process requests
+
+You can now test an authentication with:
+
+    docker exec -i -t radiusd radtest demo_user badpassword 127.0.0.1 10 testing123
+    docker exec -i -t radiusd radtest demo_user <radius show_secret value here> 127.0.0.1 10 testing123
+
+You should see Access-Accept or Access-Reject based on your calls.
+
+Finally, to expose this to a wifi infrastructure, add your NAS in config.ini:
+
+    [client.access_point]
+    ipaddr = <some ipadd>
+    secret = <random value>
+
+And re-create/run your docker instance with `-p 1812:1812 -p 1812:1812/udp` ...
+
+If you have any issues, check the logs from the radius output they tend to indicate the cause
+of the problem.
+
+Note the radius container *is* configured to provide Tunnel-Private-Group-ID so if you wish to use
+wifi assigned vlans on your infrastructure, you can assign these by groups in the config.ini.
+
+# Raw actions
+
+The server has a low-level stateful API you can use for more complex or advanced tasks on large numbers
+of entries at once. Some examples are below, but generally we advise you to use the apis as listed
+above.
+
+    # Create from json (group or account)
     cargo run -- raw create -H https://localhost:8080 -C ../insecure/ca.pem -D admin example.create.account.json
+    cargo run -- raw create  -H https://localhost:8080 -C ../insecure/ca.pem -D idm_admin example.create.group.json
 
-Give it permissions
+    # Apply a json stateful modification to all entries matching a filter
-
     cargo run -- raw modify -H https://localhost:8080 -C ../insecure/ca.pem -D admin '{"Or": [ {"Eq": ["name", "idm_person_account_create_priv"]}, {"Eq": ["name", "idm_service_account_create_priv"]}, {"Eq": ["name", "idm_account_write_priv"]}, {"Eq": ["name", "idm_group_write_priv"]}, {"Eq": ["name", "idm_people_write_priv"]}, {"Eq": ["name", "idm_group_create_priv"]} ]}' example.modify.idm_admin.json
+    cargo run -- raw modify -H https://localhost:8080 -C ../insecure/ca.pem -D idm_admin '{"Eq": ["name", "idm_admins"]}' example.modify.idm_admin.json
 
-Show the account details now:
+    # Search and show the database representations
-
     cargo run -- raw search -H https://localhost:8080 -C ../insecure/ca.pem -D admin '{"Eq": ["name", "idm_admin"]}'
     > Entry { attrs: {"class": ["account", "memberof", "object"], "displayname": ["IDM Admin"], "memberof": ["idm_people_read_priv", "idm_people_write_priv", "idm_group_write_priv", "idm_account_read_priv", "idm_account_write_priv", "idm_service_account_create_priv", "idm_person_account_create_priv", "idm_high_privilege"], "name": ["idm_admin"], "uuid": ["bb852c38-8920-4932-a551-678253cae6ff"]} }
 
-Set the password
+    # Delete all entries matching a filter
-
+    cargo run -- raw delete -H https://localhost:8080 -C ../insecure/ca.pem -D idm_admin '{"Eq": ["name", "test_account_delete_me"]}'
-    cargo run -- account credential set_password -H https://localhost:8080 -C ../insecure/ca.pem -D admin idm_admin
-
-Or even better:
-
-    cargo run -- account credential generate_password -H https://localhost:8080 -C ../insecure/ca.pem -D admin idm_admin
-
-Show it works:
-
-    cargo run -- self whoami -H 'https://localhost:8080' -C ../insecure/ca.pem -D idm_admin
-
-Now our service account can create and administer accounts and groups:
-
-    cargo run -- raw create  -H https://localhost:8080 -C ../insecure/ca.pem -D idm_admin example.create.group.json
-
-And of course, as the idm_admin, we can't write back to admin:
-
-    cargo run -- account credential generate_password -H https://localhost:8080 -C ../insecure/ca.pem -D idm_admin admin
-
-Nor can we escalate privs (we are not allow to modify HP groups):
-
-    cargo run -- raw modify -H https://localhost:8080 -C ../insecure/ca.pem -D idm_admin '{"Eq": ["name", "idm_admins"]}' example.modify.idm_admin.json
-
-So we have a secure way to manage the identities in the directory, without giving full control to any one account!

kanidm_rlm_python/test_data/config.ini

@@ -1,29 +1,29 @@
 [kanidm_client]
-url = https://172.17.0.3:8080
+url = https://172.17.0.2:8080
-ca = /data/ca.pem
 strict = false
-user = radius_server
+ca = /data/ca.crt
-secret = DYDVFqk1auAhFWrD1wzJnYBrKGFhwlxEQc2t5JK0vx3sTymj
+user = radius_service_account
+secret = XRELDJUh2pk6RcxRzgScKLOAQd7hNk3RZHe73gFo8BM8D3Iq
 
 ; default vlans for groups that don't specify one.
 [DEFAULT]
-vlan = 10
+vlan = 1
 
-[group.idm_admins]
+; [group.test]
-vlan = 12
+; vlan =
 
 [radiusd]
 ca = /data/certs/ca.pem
 key =  /data/certs/key.pem
 cert = /data/certs/cert.pem
 dh = /data/certs/dh
-required_group = idm_admins
+required_group = radius_access_allowed
 
 [client.localhost]
 ipaddr = 127.0.0.1
 secret = testing123
 
 [client.docker]
-ipaddr = 172.17.0.0/24
+ipaddr = 172.17.0.0/16
-secret = docker123
+secret = testing123