README.md 5.05 KB
Newer Older
1 2 3 4 5 6
# OIDC client stubs for AURA

In this repository we provide different client stubs and functions, which
can be used to authenticate against AURA components and use the resulting
bearer token to access the different AURA APIs.

7 8 9 10
If you are unsure what all this OIDC is about, take a look at Nate Barbettini's
talk [OAuth 2.0 and OpenID Connect (in plain English)](https://www.youtube.com/watch?v=996OiexHze0).
You can also take a peek at the [OpenID Connect FAQs and Q&As](https://openid.net/connect/faq/)
if want to check if you already know everything you need to know about the topic.
11 12 13 14 15 16 17 18 19 20 21

## Setup of the OIDC client

In any case you will need to have a correct setup of an OIDC client in the
AURA Steering component. The values you configure there have to correspond
with the values you set in your client config file, whether you use the
Shell, Python or Javascript functions.

Also make sure to have the correct response type set, that corresponds to
the OIDC flow you use in your client.

22 23
In the next section specifc setups of the client stubs are explained.

24 25
## Usage

26 27
### Bash

28 29 30
For the shell functions take a look at [bash/main.sh](bash/main.sh) as a
starting point. This shows how to use the include files and get a token
with one of the three provided flows.
31 32 33

### Python

34 35 36 37 38 39
The file [python/main.py](python/main.py) provides a full demo of all flows
that are implemented.

You can use it directly to retrieve tokens and make a test call to the steering
and tank APIs with a token. For that to work, you have to setup your config
first:
40

41 42 43 44 45
- change into the _python_ directory
- copy the _config.sample.py_ file to _config.py_ and update any fields in it
  that do not yet correspond to your OIDC setup and the user account you want
  to use for this
- now call the _main.py_ script with the _-h_ option to get some usage info
46

47 48 49 50 51 52 53 54 55 56 57 58 59 60
```bash
$ python3 main.py -h
```

Now you are good to go and facilitate the demo client to retrieve access codes
and tokens. If you are only interested in using the relevant functions from
the steering package, take a look at the few lines in the conditional blocks
in _main.py_ that start with a comment like `# demo of the ... flow`. This
is all you need, when you want to integrate this into your own script.
Make sure to have the config right, that can be imported from _config.py_
(or can also be set directly in your script) and to set the `code` value
in the `parameters` dictionary, depending on what flow you choose (e.g.
`parameters["code"] = "it_token token"` for an implicit flow).

61 62 63 64 65 66 67
### Javascript

For the JS client the approach is a bit different, as the most probable
usage will be on some webspace and therefore we can use the browser for
all redirecting. While the implementation of the flow stages is therefore
much simpler, we need a separate callback page.

68
Also if you test this locally as a _file://_ in the browser, the automatic
69 70 71 72 73 74 75
redirect to the callback page after successful authentication will not work.
In that case you have to use the developer console and check the last POST
request in the network monitor and use the `Location:` header manually.
If you put this on any local or remote web server so that you can access it
through HTTP, this should work all fine.

Take a look at the [javascript/index.html](javascript/index.html) page for
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
a start. The [javascript/steering/implicit.js](javascript/steering/implicit.js)
and the [javascript/steering/flow_stages.js](javascript/steering/flow_stages.js)
are quite short, compared to their Python and Bash counterparts, because we
let the browser and the user handle all forms and redirects. The callback
is then handled by the [javascript/callback.html](javascript/callback.html)
page, which returns to _index.html_ after it has written all relevant info
into the browsers localStorage, so that the index page can access and display
it.

For everything to work fine, first create a copy of the _config.sample.js_
file to _config.js_ and update the fields that do not correspond with your
specific setup. Make sure to use appropriate redirect URIs in the config
as well as in the OIDC client setup in _steering_.

> __Note on structuring__: this could all certainly be more compact in one file
> rather then splitting it to _main.js_, _implicit.js_ and _flow_stages.js_.
> Even the separate _callback.html_ would not be neccessary if we let
> _index.html_ also handle the callback. But this way the code can be
> better compared to the Python and Bash client stubs.
95 96 97 98 99

## Planned and upcoming features

- Functions to refresh token before it expires
- Add at least one call to the API including a bearer token in the main demos
100
    - done for python, still todo for bash and javascript
101 102
- Test (and provide sensible error message) for
    - invalid flow type
103
    - invalid redirect uris
104 105 106 107
    - invalid credentials
- For the bash client stub:
    - add user-agent header and make it configurable
    - make functions exit at the end of each stage in case of errors
108
    - make it fully POSIX/dash compliant
109 110 111 112
- For the python client stub:
    - use raise instead of sys.exit in error cases
- Add checks for state and nonce
- Check, why hybrid flow does not return access code