add keycloak sso documentation #151
Conversation
goseind
force-pushed
the
issue-513-generic-oidc
branch
from
bdb2529
to
ae24591
Compare
|
Note for reviewer: The commits need to be squashed before merging |
mdonadoni
force-pushed
the
issue-513-generic-oidc
branch
from
fd06faf
to
4ac41d5
Compare
mdonadoni
force-pushed
the
issue-513-generic-oidc
branch
from
4ac41d5
to
085c4de
Compare
| @@ -24,8 +24,64 @@ Helm value accordingly. | |||
|
|
|||
| ## User registration via Single Sign-On | |||
|
|
|||
| Handling of users with Single Sign-On (SSO) is also possible. Currently, | |||
| this is only available for CERN deployments via [`components.reana_ui.cern_sso`](https://github.com/reanahub/reana/tree/master/helm/reana) | |||
| Handling of users with Single Sign-On (SSO) is also possible. Currently SSO is supported for CERN as well as for any third-party SSO provider which supports [Keycloak](https://www.keycloak.org/). | |||
There was a problem hiding this comment.
"Handling of users" may have some negative connotations; perhaps say "User access through Single-Sign-On (SSO) authentication is also possible". (More neutral.)
There was a problem hiding this comment.
REANA currently supports CERN SSO as well as any third-party...
| ### Keycloak Single Sign-On Configuration | ||
|
|
||
| First of all, to integrate REANA with your Keycloak instance, you need to create a new client from the Keycloak's admin dashboard. | ||
| There are many configuration options, but these are the minimal changes you have to make: |
There was a problem hiding this comment.
There are many configurations options; the following are the minimal ones that you should set:
| First of all, to integrate REANA with your Keycloak instance, you need to create a new client from the Keycloak's admin dashboard. | ||
| There are many configuration options, but these are the minimal changes you have to make: | ||
|
|
||
| - _Valid Redirect URIs_ should be set to `https://<your-reana-hostname>/api/oauth/authorized/keycloak/` (see Keycloak's [Access Settings](https://www.keycloak.org/docs/latest/server_admin/#access-settings)) |
There was a problem hiding this comment.
You can use semicolon after list item, and full stop after last item, following traditional English separator style for long lists:
- first long phrase;
- second long phrase.;
- third final phrase.
| First of all, to integrate REANA with your Keycloak instance, you need to create a new client from the Keycloak's admin dashboard. | ||
| There are many configuration options, but these are the minimal changes you have to make: | ||
|
|
||
| - _Valid Redirect URIs_ should be set to `https://<your-reana-hostname>/api/oauth/authorized/keycloak/` (see Keycloak's [Access Settings](https://www.keycloak.org/docs/latest/server_admin/#access-settings)) |
There was a problem hiding this comment.
Shall we add example.org domain?
There was a problem hiding this comment.
I have used reana.example.org and keycloak.example.org
| - _Valid Redirect URIs_ should be set to `https://<your-reana-hostname>/api/oauth/authorized/keycloak/` (see Keycloak's [Access Settings](https://www.keycloak.org/docs/latest/server_admin/#access-settings)) | ||
| - _Client authentication_ should be enabled in order to get the client ID and the client secret (see Keycloak's [Confidential client credentials](https://www.keycloak.org/docs/latest/server_admin/#_client-credentials)) | ||
|
|
||
| You can then configure REANA to use your third-party SSO provider by adding an item with the needed configuration to the [`login`](https://github.com/reanahub/reana/tree/master/helm/reana) list in the Helm values: |
There was a problem hiding this comment.
In the beginning of this section, we say "your Keycloak instance". Here, we say "your third-party SSO provider". We could harmonise the two to say "Your Keycloak instance" everywhere, or "your Keycloak provider", etc.
(The SSO is used above in the little introductory text.)
There was a problem hiding this comment.
I have changed to "your Keycloak instance" everywhere
| userinfo_url: "https://<your-provider-hostname>/auth/realms/your-realm/protocol/openid-connect/userinfo" | ||
| ``` | ||
|
|
||
| Then specify the provided client ID and client secret under the [`secrets.login`](https://github.com/reanahub/reana/tree/master/helm/reana) Helm value: |
There was a problem hiding this comment.
"provided" may be too abstract. We could rephrase to be more concrete, for example:
You should then take the values of the SSO client ID and the SSO client secret that you obtained when you created your SSO application in the Keycloak dashboard and add it under the secrets.login Helm value:
| ```yaml | ||
| secrets: | ||
| login: | ||
| your-provider: |
There was a problem hiding this comment.
Shall we use your_provider to avoid dashes vs underscores?
Alternatively, we can call it myprovider without any spaces, which should make the YAML snippet more easily usable by copy/paste?
Or something "more realistic" such as reana.example.org, sso.example.org.
There was a problem hiding this comment.
I have changed it to "yourprovider". I have kept "provider" in this case to avoid confusion with "keycloak" that is used everywhere else, as this value can be fully customised by the user.
| consumer_secret: <your-client-secret> | ||
| ``` | ||
|
|
||
| !!! note |
There was a problem hiding this comment.
The note could be turned into a regular text:
Note that the key "your-provider" must match the internal identifier name you have chosen above as the name of your SSO provider.
|
|
||
| !!! note | ||
|
|
||
| Note that `secrets.login` is a dictionary, whose key must match the `name` provided in the `login` list, which in this example is `your-provider`. |
There was a problem hiding this comment.
This starts a new "section" in the configuration, so we can say:
Furthermore, given that...
|
|
||
|  | ||
|
|
||
| For further information on how to use Keycloak, see [Keycloak’s own documentation](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients). |
There was a problem hiding this comment.
see Keycloak's documentation
(no need to say "own")
mdonadoni
force-pushed
the
issue-513-generic-oidc
branch
from
e8717c2
to
06eb675
Compare
mdonadoni
force-pushed
the
issue-513-generic-oidc
branch
from
06eb675
to
01c4e8b
Compare
mdonadoni
force-pushed
the
issue-513-generic-oidc
branch
from
01c4e8b
to
7e2711a
Compare
|
Rebased, squashed and merged. Thanks @goseind for the great job! |
Perfect, thank you for reviewing and giving it the final touch 🥳 |
This PR adds documentation for the new Keycloak SSO login option.
fixes reanahub/reana-server#513