summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2018-02-09 13:53:33 +0200
committerLars Wirzenius <liw@liw.fi>2018-02-09 13:56:43 +0200
commitf1f291b270b96fe1511286cb807f02c9741b0d71 (patch)
tree509a7f697685e9282fbdc6838fb037ff6cb5e4dd /doc
parent3b208da0461f5a129fcbc527fbfdd9ed8309d077 (diff)
downloadqvisqve-f1f291b270b96fe1511286cb807f02c9741b0d71.tar.gz
Rename: to Qvisqve
Diffstat (limited to 'doc')
-rw-r--r--doc/arch.mdwn63
-rwxr-xr-xdoc/build.sh2
-rw-r--r--doc/config.mdwn20
-rw-r--r--doc/qvisqve.css (renamed from doc/salami.css)0
4 files changed, 42 insertions, 43 deletions
diff --git a/doc/arch.mdwn b/doc/arch.mdwn
index c0dab97..62e46c9 100644
--- a/doc/arch.mdwn
+++ b/doc/arch.mdwn
@@ -1,23 +1,23 @@
---
-title: "Architecture of Salami, an authorization server"
+title: "Architecture of Qvisqve, an authorization server"
author: QvarnLabs Ab
date: work-in-progress
...
# Introduction
-**What.** Salami is an authorization server. At this stage, it is an
+**What.** Qvisqve is an authorization server. At this stage, it is an
[OAuth2][] authorization server, but later on it will grow into a
-provider for [OpenID Connect][]. Salami controls access to a web API:
-the API client authenticates itself to Salami, gets an access token
-from Salami, and gives the access token to the API server. This
+provider for [OpenID Connect][]. Qvisqve controls access to a web API:
+the API client authenticates itself to Qvisqve, gets an access token
+from Qvisqve, and gives the access token to the API server. This
de-couples the acts of authentication and authorization and resource
access, which simplifies the individual software components.
[OAuth2]: https://en.wikipedia.org/wiki/OAuth
[OpenID Connect]: https://en.wikipedia.org/wiki/OpenID_Connect
-**Why.** Salami is not the first server of its kind. We wrote Salami
+**Why.** Qvisqve is not the first server of its kind. We wrote Qvisqve
because we wanted something we liked:
* is fully free, open source software
@@ -41,7 +41,7 @@ is cumbersome, and not simple.
[Gluu]: https://www.gluu.org/
-**Usage driven development.** We develop Salami mainly based on the
+**Usage driven development.** We develop Qvisqve mainly based on the
needs of actual users, not to complete feature comparsion matrices.
## Glossary
@@ -52,12 +52,11 @@ needs of actual users, not to complete feature comparsion matrices.
# Current state
-**Currently, Salami does not exist.** We have just started developing
-it. The first development phase of Salami aims to produce an OAuth2
-authorization server that supports the client credential grant only.
-This means only the API client authenticates itself to Salami, but not
-the actual end-user. This is so that we can use Salami with the
-[Qvarn][] server and have the Qvarn API tests pass.
+**Currently, alpha level.** Qvisqve is an OAuth2 authorization server
+that supports the client credential grant only. This means only the
+API client authenticates itself to Qvisqve, but not the actual
+end-user. This is so that we can use Qvisqve with the [Qvarn][] server
+and have the Qvarn API tests pass.
[Qvarn]: http://qvarn.org/
@@ -69,7 +68,7 @@ clients.
## Vision for the future
-In the longer term, we aim for Salami to be an OpenID provider using
+In the longer term, we aim for Qvisqve to be an OpenID provider using
the OpenID Connect protocol. This includes being able to have the
end-user authenticate and authorize use of resources. We will make it
simple and flexible to provide authentication methods (such as
@@ -77,31 +76,31 @@ username/password, client-side certificates, and U2F tokens).
We will be replacing the static configuration file, with the list of
clients, with Qvarn. Eventually, one goal is to make it possible to
-allow every person registered in Qvarn to authenticate with Salami.
+allow every person registered in Qvarn to authenticate with Qvisqve.
-Eventually, we aim to have Salami certified as a compliant OpenID
+Eventually, we aim to have Qvisqve certified as a compliant OpenID
Connect implementation.
-We also intend to make Salami be flexible, easy, and secure.
+We also intend to make Qvisqve be flexible, easy, and secure.
# Known problems and things to solve later
-The main problem of Salami at this stage is that it doesn't exist. All
+The main problem of Qvisqve at this stage is that it doesn't exist. All
other problems can be derived from that.
We don't have a good way of rotating the token signing keys.
# Requirements
-For the first development phase of Salami, our acceptance criteria
+For the first development phase of Qvisqve, our acceptance criteria
are:
-* setting up a Salami instance is simple: the software should be
+* setting up a Qvisqve instance is simple: the software should be
provided as a Debian package installable on Debian 9 (stretch), and
a corresponding Ansible playbook that configures the instance
-* configuring a Qvarn instance to use the Salami instance is simple:
- the Ansible playbook for Qvarn should be updated to work with Salami
+* configuring a Qvarn instance to use the Qvisqve instance is simple:
+ the Ansible playbook for Qvarn should be updated to work with Qvisqve
instead of Gluu
* the Qvarn API tests pass
@@ -117,7 +116,7 @@ about storing API client secrets in an encrypted fashion.
# Architecture overview
-Salami provides an HTTP API interface for authentication. The only
+Qvisqve provides an HTTP API interface for authentication. The only
relevant endpoint is `/token` and to use it, the client must
authenticate itself using its "client id" and "client secret" using
HTTP Basic Authentication. A successful response will have the access
@@ -126,7 +125,7 @@ token in its JSON body.
A request:
POST /token HTTP/1.1
- Host: salami.example.com
+ Host: qvisqve.example.com
Authorization: Basic c2FsYW1pOnBhc3N3b3Jk
Content-Type: application/x-www-form-urlencoded
@@ -153,15 +152,15 @@ into requests it makes.
## Components
-Salami consists of several components
+Qvisqve consists of several components
@startuml
-title Salami components
+title Qvisqve components
component [API client] as client
-node "Salami" {
+node "Qvisqve" {
component [Haproxy] as haproxy
- component [Salami\nbackend] as backend
- component [Salami\nconfiguration] as config
+ component [backend] as backend
+ component [configuration] as config
}
client -> haproxy : 2. https
@@ -171,17 +170,17 @@ haproxy <- backend : 4. access token
client <- haproxy : 5. access token
@enduml
-**haproxy** is a load balancer. For Salami we use it to provide TLS
+**haproxy** is a load balancer. For Qvisqve we use it to provide TLS
for communication with the client.
-The **backend** implements the actual Salami HTTP endpoints and
+The **backend** implements the actual Qvisqve HTTP endpoints and
creates and returns access tokens to the client.
The **configuration** lists the API clients (the id, the secret, and
any scopes the client is allowed to have), as well as the RSA keys
used to sign the access token. The API provider (Qvarn) will be
configured to know the public RSA key so that it can verify that an
-access token has been created by Salami.
+access token has been created by Qvisqve.
The client and haproxy use TLS. haproxy and the backend use plain
HTTP, but they will be deployed in an environment where the plain text
diff --git a/doc/build.sh b/doc/build.sh
index 418fa26..661266f 100755
--- a/doc/build.sh
+++ b/doc/build.sh
@@ -40,4 +40,4 @@ pandoc --toc \
-Vgeometry:"top=2cm, bottom=2.5cm, left=2cm, right=1cm" \
--chapters \
-o "$output.pdf" "$tmp/foo.mdwn"
-pandoc --toc -o "$output.html" --number-sections --self-contained -H salami.css "$tmp/foo.mdwn"
+pandoc --toc -o "$output.html" --number-sections --self-contained -H qvisqve.css "$tmp/foo.mdwn"
diff --git a/doc/config.mdwn b/doc/config.mdwn
index 278b99b..e803597 100644
--- a/doc/config.mdwn
+++ b/doc/config.mdwn
@@ -1,18 +1,18 @@
---
-title: "Configuring Salami, an authorization server"
+title: "Configuring Qvisqve, an authorization server"
author: QvarnLabs Ab
date: work-in-progress
...
# Introduction
-This document explains how to configure Salami, which is an
-authorization server.
+This document explains how to configure Qvisqve, which is an
+authorization server and identity provider.
# Installation
-Install Salami from a Debian package. There is one at
-<http://code.liw.fi/debian/pool/main/s/salami/>. Add the following
+Install Qvisqve from a Debian package. There is one at
+<http://code.liw.fi/debian/pool/main/s/qvisqve/>. Add the following
line to the APT sources list:
- deb http://code.liw.fi/debian stretch main
@@ -87,11 +87,11 @@ install, the current key is:
# Configure
-Install a configuration at `/etc/salami/salami.yaml` with the
+Install a configuration at `/etc/qvisqve/qvisqve.yaml` with the
following content:
log:
- - filename: /var/log/salami.log
+ - filename: /var/log/qvisqve.log
token-issuer: iss
token-audience: aud
token-public-key: ssh-rsa ...
@@ -100,12 +100,12 @@ For now, any ssh public key will do for the `token-public-key`.
# Run
-To run Salami, run this command:
+To run Qvisqve, run this command:
- /usr/bin/start_salami
+ /usr/bin/start_qvisqve
After a few seconds, the 12765 port should be accepting requests:
curl http://127.0.0.1:12765/version
-This should report the current Salami version.
+This should report the current Qvisqve version.
diff --git a/doc/salami.css b/doc/qvisqve.css
index 86f806e..86f806e 100644
--- a/doc/salami.css
+++ b/doc/qvisqve.css