Commit ef11a15f authored by David Trattnig's avatar David Trattnig
Browse files

Initial version.

parent eb2ca0cb
<img src="../../assets/images/aura-logo.png" width="250" />
# OpenID Client Configuration
1. [OpenID Client Configuration](#openid-client-configuration)
1. [Required OIDC Clients](#required-oidc-clients)
2. [Registering clients at Steering](#registering-clients-at-steering)
1. [Registering OIDC clients on the command-line](#registering-oidc-clients-on-the-command-line)
2. [Registering OIDC clients via the admin interface](#registering-oidc-clients-via-the-admin-interface)
1. [Create an RSA Key](#create-an-rsa-key)
2. [Create OIDC client for Dashboard](#create-oidc-client-for-dashboard)
3. [Create OIDC client for Tank](#create-oidc-client-for-tank)
3. [Setting the client configuration](#setting-the-client-configuration)
1. [Configuring Dashboard](#configuring-dashboard)
2. [Configuring Tank](#configuring-tank)
AURA is using [OpenID](https://en.wikipedia.org/wiki/OpenID) for authentication and authorizing
access to restricted API endpoints.
We are using [OpenID Connect (OIDC)](https://openid.net/connect/) for the OpenID handshakes.
[Steering](https://gitlab.servus.at/aura/steering) is the central OpenID provider. All applications requesting access,
need to get an authorization from Steering. Those applications are called *OIDC clients*.
## Required OIDC Clients
In order to properly setup AURA, you'll need to configure following OpenID clients:
- Dashboard (explicit flow, requiring user-interaction for approval)
- Tank (implicit flow, no user-interaction required)
The registration and configuration steps below use [the default hosts & ports](../development/default-hosts-ports.md).
In case of a [Production Deployment](../administration/index.md) you'll probably have substitutions like following:
- Steering: *localhost:8080 → aura-host.org/admin*
- Dashboard: *localhost:8000 → aura-host.org*
- Tank: *localhost:8040 → aura-host.org/tank*
## Registering clients at Steering
### Registering OIDC clients on the command-line
First navigate to your Steering project location.
1. Create an RSA Key
```bash
steering$ python manage.py creatersakey
```
2. Create OIDC client for Dashboard
```bash
steering$ python manage.py create_oidc_client dashboard public -r "id_token token" -u https://localhost:8080/oidc_callback.html -u https://localhost:8080/oidc_callback_silentRenew.html -p https://localhost:8080.o94.at/
```
**Important:** Remember to note the client id and secret for the configuration section below.
1. Create OIDC client for Tank
```bash
steering$ python manage.py create_oidc_client tank confidential -r "code" -u https://localhost:8040/auth/oidc/callback
```
**Important:** Remember to note the client id and secret for the configuration section below.
### Registering OIDC clients via the admin interface
Follow these three steps to register Dashboard and Tank in the OpenID admin section of Steering.
#### Create an RSA Key
In the admin interface navigate to *OpenID Connect Provider* and *generate an RSA Key*.
#### Create OIDC client for Dashboard
Here you'll need to choose following settings:
```ini
Client Type: Public
Response Type: id_token token (Implicit Flow)
JWT Algorithm: RS256
Require Consent?: No
Reuse Consent?: Yes
```
And enter these redirect URLs:
```s
http://localhost:8080/static/oidc_callback.html
http://localhost:8080/static/oidc_callback_silentRenew.html
```
Note, that these URLs have to match exactly the
ones you configure in your `.env.development` or `.env.production` files here
in the dashboard source. This also means that if you use `localhost` in steering,
you must not put `127.0.0.1` or any aquivalent in your dashboard config, but
use exactly the same string (and vice versa).
Note the client to use in your Dashboard config file.
<a href="../../assets/images/steering-openid-dashboard.png"><img src="../../assets/images/steering-openid-dashboard.png" width="500" /></a>
> **TODO**: *Replace image with a current screenshot of Steering*
#### Create OIDC client for Tank
Here you'll need to choose following settings:
```ini
Client Type: Confidential
Response Type: code (Authorization Code Flow)
JWT Algorithm: RS256
Require Consent?: No
Reuse Consent?: Yes
```
And enter that redirect URL:
```s
http://localhost:8040/auth/oidc/callback
```
Note the client id and secret to use in your Tank config file.
<a href="../../assets/images/steering-openid-tank.png"><img src="../../assets/images/steering-openid-tank.png" width="500" /></a>
> **TODO**: *Replace image with a current screenshot of Steering*
## Setting the client configuration
When configuring a client, always remind yourself to use the hostname. When using the IP address for OIDC redirect URLs
you might get unexpected behaviour or being unable to authenticate at all.
### Configuring Dashboard
In the Dashboard folder, edit your `.env.production ` or `.env.development ` respectively, and carefully review
if these URLs are matching the ones in the
```ini
VUE_APP_API_STEERING_OIDC_REDIRECT_URI = http://localhost:8080/oidc_callback.html
VUE_APP_API_STEERING_OIDC_REDIRECT_URI_SILENT = http://localhost:8080/oidc_callback_silentRenew.html
```
Then set the client id and secret, which you noted from the previous step:
```ini
VUE_APP_OIDC_CLIENT_ID = %YOUR_ID%
```
Additionally confirm that your Steering URL and port is also matching the instance your are running at:
```ini
VUE_APP_API_STEERING_OIDC_URI = http://localhost:8000/openid
```
### Configuring Tank
In the Tank configuration file set review the given URLS.
Replace `${OIDC_CLIENT_ID}` and `${OIDC_CLIENT_SECRET}` with your client ID and secret, or set the environment variables accordingly.
```yaml
oidc:
issuer-url: http://localhost:8000/openid
client-id: ${OIDC_CLIENT_ID}
client-secret: ${OIDC_CLIENT_SECRET}
callback-url: http://localhost:8040/auth/oidc/callback
```
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment