Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update docs #367

Merged
merged 15 commits into from
Jan 30, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python 3.9
uses: actions/setup-python@v2
- name: Set up Python 3.10
uses: actions/setup-python@v5
with:
python-version: 3.9
python-version: "3.10"
- name: Install deps
run: |
python -m pip install --upgrade pip
Expand Down
29 changes: 1 addition & 28 deletions docs/guide/login.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,4 @@ Login

Users can log in to IceProd like any other web application.

Authentication is handled by an external plugin
such as `LDAP`_.

.. _LDAP: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol

.. note::
:class: icecube

LDAP authentication is set up for IceCube users.


Two Factor Authentication
-------------------------

Certain pages and actions require additional authentication. When a new
account is registered with IceProd, two-factor authentication must be
set up.

IceProd uses time-based one-time passwords (`RFC 6238`_), as used by
Google, GitHub, and others. Using a phone app such as Google Authenticator,
a barcode image specific to each user can be scanned and registered. The
app will then generate short codes valid for 30 seconds each.

Example barcode image:

.. image:: ../static/2fa_barcode.png

.. _RFC 6238: https://tools.ietf.org/html/rfc6238
Authentication is handled by IceCube SSO.
52 changes: 47 additions & 5 deletions docs/guide/restapi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,58 @@ Authentication
To view datasets, call actions on datasets, or submit new datasets,
authentication with a token is required.

An authentication token can be obtained within the account settings
in the website. This can be added to requests as the `Authorization` header.
An authentication token can be obtained using the python package
`wipac-rest-tools`. For example::

python3 -m venv venv
. venv/bin/activate
pip install wipac-rest-tools
curl -o get_token.py https://raw.githubusercontent.com/WIPACrepo/rest-tools/master/examples/get_device_credentials_token.py
python get_device_credentials_token.py iceprod-public

The access token will be valid for 1 hour.

This can be added to requests as the `Authorization` header.
As an example, here is a query to get the list of all datasets::

curl -XGET -H 'Authorization: bearer XXXXXXXX-your-token-here-XXXXX' https://iceprod2-api.icecube.wisc.edu/datasets

.. danger::

Anyone with the authentication token is basically you. It is valid
for any action that does not require :ref:`Two Factor Authentication`.
Be careful with the token!
Anyone with the authentication token is basically you. Be careful with the token!


Scripting
^^^^^^^^^

When writing a python script, you can use our rest client to automatically
manage tokens for you. Just install `wipac-rest-tools` as shown above.
There are also sync and async code options:

Sync::

from rest_tools.client import SavedDeviceGrantAuth
api = SavedDeviceGrantAuth(
address='https://api.iceprod.wisc.edu',
token_url='https://keycloak.icecube.wisc.edu/auth/realms/IceCube',
filename='.iceprod-auth',
client_id'iceprod-public'
)
# get a list of datasets
result = api.request_seq('GET', '/datasets', {})
for dataset, metadata in result.items():
# do something with the dataset

Async::

from rest_tools.client import SavedDeviceGrantAuth
api = SavedDeviceGrantAuth(
address='https://api.iceprod.wisc.edu',
token_url='https://keycloak.icecube.wisc.edu/auth/realms/IceCube',
filename='.iceprod-auth',
client_id'iceprod-public'
)
# get a list of datasets
result = await api.request('GET', '/datasets', {})
for dataset, metadata in result.items():
# do something with the dataset
2 changes: 1 addition & 1 deletion docs/server/rest_api/auth.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Auth
===============

.. automodule:: iceprod.server.rest.auth
.. automodule:: iceprod.rest.handlers.auth
2 changes: 1 addition & 1 deletion docs/server/rest_api/config.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Config
=================

.. automodule:: iceprod.server.rest.config
.. automodule:: iceprod.rest.handlers.config
2 changes: 1 addition & 1 deletion docs/server/rest_api/datasets.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Datasets
===================

.. automodule:: iceprod.server.rest.datasets
.. automodule:: iceprod.rest.handlers.datasets
2 changes: 1 addition & 1 deletion docs/server/rest_api/grids.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Grids
================

.. automodule:: iceprod.server.rest.grids
.. automodule:: iceprod.rest.handlers.grids
2 changes: 1 addition & 1 deletion docs/server/rest_api/jobs.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Jobs
===============

.. automodule:: iceprod.server.rest.jobs
.. automodule:: iceprod.rest.handlers.jobs
2 changes: 1 addition & 1 deletion docs/server/rest_api/logs.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Logs
===============

.. automodule:: iceprod.server.rest.logs
.. automodule:: iceprod.rest.handlers.logs
2 changes: 1 addition & 1 deletion docs/server/rest_api/pilots.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Pilots
=================

.. automodule:: iceprod.server.rest.pilots
.. automodule:: iceprod.rest.handlers.pilots
2 changes: 1 addition & 1 deletion docs/server/rest_api/task_stats.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Task Stats
=====================

.. automodule:: iceprod.server.rest.task_stats
.. automodule:: iceprod.rest.handlers.task_stats
2 changes: 1 addition & 1 deletion docs/server/rest_api/tasks.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
REST API - Tasks
================

.. automodule:: iceprod.server.rest.tasks
.. automodule:: iceprod.rest.handlers.tasks
69 changes: 32 additions & 37 deletions requirements-docs.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@
#
# pip-compile --extra=docs --output-file=requirements-docs.txt
#
alabaster==0.7.13
alabaster==0.7.16
# via sphinx
anyio==4.0.0
anyio==4.2.0
# via httpx
asyncache==0.3.1
# via iceprod (setup.py)
babel==2.13.1
babel==2.14.0
# via sphinx
boto3==1.28.81
boto3==1.34.31
# via iceprod (setup.py)
botocore==1.31.81
botocore==1.34.31
# via
# boto3
# s3transfer
Expand All @@ -23,7 +23,7 @@ cachetools==5.3.2
# asyncache
# iceprod (setup.py)
# wipac-rest-tools
certifi==2023.7.22
certifi==2023.11.17
# via
# httpcore
# httpx
Expand All @@ -33,61 +33,61 @@ cffi==1.16.0
# via cryptography
charset-normalizer==3.3.2
# via requests
cryptography==41.0.5
cryptography==42.0.2
# via
# iceprod (setup.py)
# pyjwt
# pyopenssl
dnspython==2.4.2
dnspython==2.5.0
# via pymongo
docutils==0.20.1
# via sphinx
exceptiongroup==1.1.3
exceptiongroup==1.2.0
# via anyio
h11==0.14.0
# via httpcore
httpcore==1.0.1
httpcore==1.0.2
# via httpx
httpx==0.25.1
httpx==0.26.0
# via iceprod (setup.py)
idna==3.4
idna==3.6
# via
# anyio
# httpx
# requests
imagesize==1.4.1
# via sphinx
jinja2==3.1.2
jinja2==3.1.3
# via sphinx
jmespath==1.0.1
# via
# boto3
# botocore
ldap3==2.9.1
# via iceprod (setup.py)
markupsafe==2.1.3
markupsafe==2.1.4
# via jinja2
motor==3.3.1
motor==3.3.2
# via iceprod (setup.py)
packaging==23.2
# via sphinx
psutil==5.9.6
psutil==5.9.8
# via iceprod (setup.py)
pyasn1==0.5.0
pyasn1==0.5.1
# via ldap3
pycparser==2.21
# via cffi
pygments==2.16.1
pygments==2.17.2
# via sphinx
pyjwt[crypto]==2.8.0
# via
# pyjwt
# wipac-rest-tools
pymongo==4.6.0
pymongo==4.6.1
# via
# iceprod (setup.py)
# motor
pyopenssl==23.3.0
pyopenssl==24.0.0
# via iceprod (setup.py)
pypng==0.20220715.0
# via qrcode
Expand All @@ -113,7 +113,7 @@ requests-futures==1.0.1
# wipac-rest-tools
requests-toolbelt==1.0.0
# via iceprod (setup.py)
s3transfer==0.7.0
s3transfer==0.10.0
# via boto3
setproctitle==1.3.3
# via iceprod (setup.py)
Expand All @@ -126,43 +126,38 @@ sniffio==1.3.0
snowballstemmer==2.2.0
# via sphinx
sphinx==7.2.6
# via
# iceprod (setup.py)
# sphinxcontrib-applehelp
# sphinxcontrib-devhelp
# sphinxcontrib-htmlhelp
# sphinxcontrib-qthelp
# sphinxcontrib-serializinghtml
sphinxcontrib-applehelp==1.0.7
# via iceprod (setup.py)
sphinxcontrib-applehelp==1.0.8
# via sphinx
sphinxcontrib-devhelp==1.0.5
sphinxcontrib-devhelp==1.0.6
# via sphinx
sphinxcontrib-htmlhelp==2.0.4
sphinxcontrib-htmlhelp==2.0.5
# via sphinx
sphinxcontrib-jsmath==1.0.1
# via sphinx
sphinxcontrib-qthelp==1.0.6
sphinxcontrib-qthelp==1.0.7
# via sphinx
sphinxcontrib-serializinghtml==1.1.9
sphinxcontrib-serializinghtml==1.1.10
# via sphinx
statsd==4.0.1
# via iceprod (setup.py)
tornado==6.3.3
tornado==6.4
# via
# iceprod (setup.py)
# wipac-rest-tools
typing-extensions==4.8.0
typing-extensions==4.9.0
# via
# anyio
# qrcode
# wipac-dev-tools
unidecode==1.3.7
unidecode==1.3.8
# via iceprod (setup.py)
urllib3==2.0.7
# via
# botocore
# requests
# wipac-rest-tools
wipac-dev-tools==1.7.1
wipac-dev-tools==1.8.2
# via
# iceprod (setup.py)
# wipac-rest-tools
Expand Down
Loading
Loading