Decision API Quickstart

This document describes a very simple use case in which you’ll see Heimdall’s Decision API in action.

Prerequisites

Configure

heimdall can be configured via environment variables, as well as using a configuration file. For simplicity reasons, we’ll use a configuration file here. So create a config file (config.yaml) with the following content:

log:
  level: info                     (1)

pipeline:
  authenticators:
    - id: anonymous_authenticator (2)
      type: anonymous
  mutators:
    - id: create_jwt              (3)
      type: jwt

rules:
  default:                        (4)
    methods:
      - GET
      - POST
    execute:
      - authenticator: anonymous_authenticator
      - mutator: create_jwt
1Here we are setting the log level to info to be able to see any log output. By default, Heimdall logs on error log level.
2Configures the anonymous authenticator.
3Configured the jwt mutator.
4Configures the default rule.

Put together, this configuration will let Heimdall create a JSON Web Token (JWT) with sub claim set to anonymous for every request on every URL for the HTTP methods GET and POST. The JWT itself will be put into the Authorization header as a bearer token.

Run in Decision operation mode

Run heimdall specifying the configuration file from above

If you’re using a binary, just execute

$ ./heimdall serve decision -c config.yaml

The above command will start heimdall in a decision operation mode. By default, the service will be served on port 4456.

Otherwise, if you’ve built a Docker image, run heimdall in the decision operation mode via

$ docker run -t -v $PWD:/heimdall/conf -p 4456:4456 \
  dadrus/heimdal:latest serve decision -c /heimdall/conf/config.yaml

In both cases, you’ll see similar output to

2022-08-04T07:40:12+02:00 INF No opentracing provider configured. Tracing will be disabled.
2022-08-04T07:40:12+02:00 INF Instantiating in memory cache
2022-08-04T07:40:12+02:00 INF Loading pipeline definitions
2022-08-04T07:40:12+02:00 WRN No rule provider configured. Only defaults will be used.
2022-08-04T07:40:12+02:00 WRN Key store is not configured. NEVER DO IT IN PRODUCTION!!!! Generating an
                          RSA key pair.
2022-08-04T07:40:12+02:00 WRN No key id for signer configured. Taking first entry from the key store
2022-08-04T07:40:12+02:00 INF Starting cache evictor
2022-08-04T07:40:12+02:00 INF Starting rule definition loader
2022-08-04T07:40:12+02:00 INF Management service starts listening on: :4457
2022-08-04T07:40:12+02:00 INF Prometheus service starts listening on: :9000
2022-08-04T07:40:12+02:00 INF Decision service starts listening on: :4456

Ignore the warnings. They are expected as we’ve neither configured a rule provider, nor have we configured a key store for JWT signing purposes. Nevertheless, the default rule can be used.

Use

Sent some request to heimdall’s decision service endpoint:

$ curl -v 127.0.0.1:4456/foobar

Here, we’re asking to apply the default rule for the foobar path using the GET HTTP verb.

On completion, you should see the Authorization header in the response, like in the output below:

*   Trying 127.0.0.1:4456...
* Connected to 127.0.0.1 (127.0.0.1) port 4456 (#0)
> GET /foobar HTTP/1.1
> Host: 127.0.0.1:4456
> User-Agent: curl/7.74.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 202 Accepted
< Server: Heimdall Decision API
< Date: Thu, 04 Aug 2022 07:45:16 GMT
< Content-Length: 0
< Authorization: Bearer eyJhbGciOiJQUzI1NiIsImtpZCI6IjJkZGIxZDM3MWU1MGFjNDQ5ZGJhNjcyNj
ZmZDRjMzU0OWZjNmRmYTYiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NTYxNjY1MTYsImlhdCI6MTY1NjE2NjIxN
iwiaXNzIjoiaGVpbWRhbGwiLCJqdGkiOiIxYjdlODdjYi0zYjdjLTQ1ZDAtYWEyZi00MTRhYmI2YjBlMzciLCJ
uYmYiOjE2NTYxNjYyMTYsInN1YiI6ImFub255bW91cyJ9.MY6fjk7K6ZNn57Mrjy6UGI1cvIMCOOEJoCQF45PH
Q34BfoPxMuTRjdVUZPX4xnT4suyWySsaU1wisgXv4CuMf4WsEUCPKOH8NKv5Zty6eXjTdWQpekDWYsHpVVwz8U
HLmrRASlo_JKErj64wPbRcQWyLMR9X-4cR28ZuH3IbyXh4-XlGNEMAVWYFaZGv1QlEd7jcw3jSVK0b5AtY-NUc
VQlccWpqWD43AE-3spchqboFuiuW5IxFGd4Mc0Dp6uepuQ-XiWEFg9rxnaxl-Grr3LfSY83oML53Akrl4lGtVB
u55QVVjduv_b2ykRnqh7Im9lSivokuVMEuSE8bN2qnqg
<
* Connection #0 to host 127.0.0.1 left intact

You should also be able to see similar output as below from the heimdall instance

...
2022-08-04T07:45:16+02:00 INF TX started _client_ip=127.0.0.1 _http_host=127.0.0.1:4456 _http_method=GET
 _http_path=/foobar _http_scheme=http _http_user_agent=curl/7.74.0 _tx_start=1659599116
2022-08-04T07:45:16+02:00 INF TX finished _access_granted=true _body_bytes_sent=0 _client_ip=127.0.0.1
 _http_host=127.0.0.1:4456 _http_method=GET _http_path=/foobar _http_scheme=http _http_status_code=202
 _http_user_agent=curl/7.74.0 _subject=anonymous _tx_duration_ms=0 _tx_start=1659599116

Last updated on Aug 4, 2022

Concepts
Proxy Quickstart