Browse Source

Add SURFconext documentation

master
Joshua Rubingh 11 months ago
parent
commit
1def9b8f85
  1. 58
      doc/SURFconext.rst
  2. BIN
      doc/_images/SURFconext_config.png
  3. BIN
      doc/_images/SURFconext_logo.png
  4. BIN
      doc/documentation.pdf
  5. 1
      doc/index.rst
  6. 921
      doc/swagger.yaml

58
doc/SURFconext.rst

@ -0,0 +1,58 @@ @@ -0,0 +1,58 @@
==========
SURFconext
==========
.. figure:: _images/SURFconext_logo.png
:align: right
:alt: SURFconext Logo
The authentication is done by SURFconext. This is an `OpenID <https://openid.net/>`_ provider for all the Universities and schools in the Netherlands.
More documentation can be found at: https://wiki.surfnet.nl/display/SURFconextdev/Get+Conexted
In order to use SURFconext, you need to make a configuration in SURFconext and then configure the API.
----------
SURFconext
----------
.. figure:: _images/SURFconext_config.png
:align: center
:alt: SURFconext Configuration
- **Client ID**: The name of the configuration. Use the API url as this is suggested in the GUI.
- **Redirect urls**: The urls where to redirect to after login. Use `localhost` urls for development. For production use: **https://api-vre.web.rug.nl/oidc/callback/**
- **Access token validity**: How long is the login token valid at SURFconext. SURFconext default 3600 seconds.
- **Is public client**: Do not use this.
- **Grants**: We need the `Authorization code` option
- **Subject type**: We need the `Persistent` option
All other options are not required for making the OpenID connection with the VRE API.
**Attention**: When you save the configuration for the first time, you will get an `Client secret`. Save this value somewhere safe. You need it later on.
Claims
======
In the last part of the configuration you need to setup which information you want to receive van de OpenID provider. If this is changed, then every user needs to login again, as the login has 'changed'
More information about which claims are available can be found here: https://wiki.surfnet.nl/display/SURFconextdev/Claims
---
API
---
After the OpenID configuration is created at SURFconext, you need to setup the API with the right variables.
In the future there is a possibility that less variables are needed. Because the used library does not support `OpendID discovery yet <https://github.com/mozilla/mozilla-django-oidc/pull/309>`_ :
For SURFconext the `well known` url is: https://connect.SURFconext.nl/oidc/.well-known/openid-configuration
- **OIDC_RP_CLIENT_ID**: The ID that is entered in the `Client ID` field. This is based on the url of the API.
- **OIDC_RP_CLIENT_SECRET**: When you create a new configuration, you will be presented with a generated secret. Store this variable safely. It will not be shown again.
- **OIDC_RP_SIGN_ALGO**: The signing algorithm. SURFconext uses `RS256`
- **OIDC_OP_AUTHORIZATION_ENDPOINT**: Full url to the authorization endpoint. In the `well known` data it is the url at `authorization_endpoint`
- **OIDC_OP_TOKEN_ENDPOINT**: Full url to the token endpoint. In the well `known data` it is the url at `token_endpoint`
- **OIDC_OP_USER_ENDPOINT**: Full url to the user info endpoint. In the well `known data` it is the url at `userinfo_endpoint`
- **OIDC_OP_JWKS_ENDPOINT**: Full url to the certification endpoint. Needed because of the `RS256` algorithm. In the well `known data` it is the url at `jwks_uri`
Two other settings depends on the VRE frontend which are used after login or logout actions.
- **LOGIN_REDIRECT_URL**: Where to redirect to after the login is successfully.
- **LOGOUT_REDIRECT_URL**: Where to redirect to after the logout is successfully.

BIN
doc/_images/SURFconext_config.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 95 KiB

BIN
doc/_images/SURFconext_logo.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.7 KiB

BIN
doc/documentation.pdf

Binary file not shown.

1
doc/index.rst

@ -18,6 +18,7 @@ The platform can be run inside a docker setup or just local for development. @@ -18,6 +18,7 @@ The platform can be run inside a docker setup or just local for development.
install
storage
models
SURFconext
API
authentication
signals

921
doc/swagger.yaml

File diff suppressed because it is too large Load Diff
Loading…
Cancel
Save