diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 5e1edb4c3..cc3513d35 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -19,8 +19,15 @@ 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. +You should have a ca.pem, cert.pem and key.pem in your kanidmd volume. The reason for requiring +TLS is explained in [why tls]. To put the certificates in place you can use a shell container +that mounts the volume such as: + +[why tls]: https://github.com/Firstyear/kanidm/blob/master/designs/why_tls.rst + + docker run --rm -i -t -v kanidmd:/data -v /my/host/path/work:/work opensuse/leap:latest cp /work/* /data/ + OR for a shell into the volume: + docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh Then you can setup the initial admin account and initialise the database into your volume. @@ -29,7 +36,7 @@ Then you can setup the initial admin account and initialise the database into yo 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 + docker run -p 8443: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 @@ -43,8 +50,8 @@ After you check out the source, navigate to: 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 + cargo run -- self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous + cargo run -- self whoami -H https://localhost:8443 --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. @@ -221,16 +228,16 @@ of entries at once. Some examples are below, but generally we advise you to use 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 + cargo run -- raw create -H https://localhost:8443 -C ../insecure/ca.pem -D admin example.create.account.json + cargo run -- raw create -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin example.create.group.json # 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 + cargo run -- raw modify -H https://localhost:8443 -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:8443 -C ../insecure/ca.pem -D idm_admin '{"Eq": ["name", "idm_admins"]}' example.modify.idm_admin.json # Search and show the database representations - cargo run -- raw search -H https://localhost:8080 -C ../insecure/ca.pem -D admin '{"Eq": ["name", "idm_admin"]}' + cargo run -- raw search -H https://localhost:8443 -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"]} } # 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 -- raw delete -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin '{"Eq": ["name", "test_account_delete_me"]}' diff --git a/designs/why_tls.rst b/designs/why_tls.rst new file mode 100644 index 000000000..64bdc92dd --- /dev/null +++ b/designs/why_tls.rst @@ -0,0 +1,35 @@ +Why TLS is required? +-------------------- + +In the getting started you may notice that we require TLS to be configure in +your container - or that you provide something *with* TLS in front like haproxy. + +This is due to a single setting on the server - secure_cookies + +What are secure cookies? +------------------------ + +Secure Cookies is a flag set in cookies that "asks" a client only to transmit them +back to the origin site if and only if https is present in the URL. + +CA verification is *not* checked - you can use invalid, out of date certificates, +or even certificates where the subjectAltName does not match. But the client +must see https:// as the destination else it *will not* send the cookies. + +How does that affect kanidm? +---------------------------- + +Kanidm's authentication system is a stepped challenge response design, where you +initially request an "intent" to authenticated. Once you establish this intent +the server set's up a session-id into a cookie, and we inform the client of +what authentication methods can proceed. + +When you then go to continue the authentication if you do NOT have a https url +the cookie with the session-id is not transmitted. The server detects this as +an invalid-state request in the authentication design and immediately disconnects +you from attempting to continue the authentication as you may be using an insecure +channel. + +Simply put, we are trying to use settings like secure_cookies to add constraints +to the server so that you *must* perform and adhere to best practices - such +as having TLS present on your communication channels. diff --git a/kanidmd/Dockerfile b/kanidmd/Dockerfile index bdd617eb2..2c91e8108 100644 --- a/kanidmd/Dockerfile +++ b/kanidmd/Dockerfile @@ -1,22 +1,21 @@ FROM opensuse/tumbleweed:latest MAINTAINER william@blackhats.net.au -EXPOSE 8080 - COPY . /home/kanidm/ WORKDIR /home/kanidm/ RUN zypper install -y timezone cargo rust gcc sqlite3-devel libopenssl-devel && \ - RUSTC_BOOTSTRAP=1 cargo build --release && \ - zypper rm -u -y cargo rust gcc && \ - zypper clean + RUSTC_BOOTSTRAP=1 cargo build --release -RUN cd /etc && \ - ln -sf ../usr/share/zoneinfo/Australia/Brisbane localtime +FROM opensuse/tumbleweed:latest + +EXPOSE 8080 +WORKDIR / +COPY --from=0 /home/kanidm/target/release/kanidmd /sbin/ VOLUME /data ENV RUST_BACKTRACE 1 -CMD ["/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:8080"] +CMD ["/sbin/kanidmd", "server", "-D", "/data/kanidm.db", "-C", "/data/ca.pem", "-c", "/data/cert.pem", "-k", "/data/key.pem", "--bindaddr", "0.0.0.0:8080"]