Add docs about enabling Single Sign-on in Central #1657
Conversation
|
|
||
| $ docker compose build && docker compose stop && docker compose up -d | ||
|
|
||
| Using Google as an Identity Provider |
There was a problem hiding this comment.
We discussed providing some guidance around how to set up an IdP for Google and maybe Azure. @lognaturel, would you be up for adding those instructions? I also think those instructions could come in a follow-up PR after release.
|
|
||
| TODO Google Chrome profiles | ||
|
|
||
| Using Azure as an Identity Provider |
There was a problem hiding this comment.
The brainstorming doc includes notes about Azure that I don't fully understand and didn't add here.
|
|
||
| To disable SSO: | ||
|
|
||
| #. In ``.env``, set ``OIDC_ENABLED`` to ``false``. Clear ``OIDC_ISSUER_URL``, ``OIDC_CLIENT_ID``, and ``OIDC_CLIENT_SECRET``. |
There was a problem hiding this comment.
It's not strictly necessary to clear the latter three variables. We probably won't clear them on our dev servers. Our dev servers are unusual in that we will often toggle SSO on and off. However, that won't be the case for most users. I think it's easiest just to tell users to clear these variables rather than that they may clear them, but aren't required to. If they don't need to keep these values on the server, it's probably best to clear them, as some of them are sensitive.
|
|
||
| .. code-block:: console | ||
|
|
||
| $ docker compose build && docker compose stop && docker compose up -d |
There was a problem hiding this comment.
I noticed that #1655 added docker compose stop in various instructions, so I included it here.
| OIDC_CLIENT_ID=my-client-id | ||
| OIDC_CLIENT_SECRET=my-client-secret |
There was a problem hiding this comment.
According to the spec, the client ID and client secret are allowed to contain the characters " or \. However, our implementation does not support that. See getodk/central#458 (comment). That said, I don't think it's useful to document that fact at this point. Alex mentioned that he hasn't seen either character in practice. Even if either character were used, I think the typical result would be a clear failure, because the Backend config file wouldn't be valid JSON.
|
|
||
| When you enable SSO, users will use their account on the identity provider to log into Central. However, users will still have a Central account that is separate from the identity provider. A Central account is not automatically created for each account on the identity provider. Instead, a Central administrator will need to create a Central account for each user of the identity provider who should be allowed to log into Central. | ||
|
|
||
| Central users will be able to change their display name shown in Central and to choose a different name from what is shown in the identity provider. However, because Central identifies users by their email address, most users will not be allowed to change their email address. Only a Central Administrator will be able to change the email address associated with a Central account. That will be needed if a user's email address changes within the identity provider. In that case, an Administrator will need to manually change the user's email address within Central to match their new address in the identity provider. |
There was a problem hiding this comment.
Email change is one of two special cases mentioned in the brainstorming doc. I didn't add the other case ("Email addresses change hands") because I'm not completely sure how to describe it.
| Enabling SSO in an Existing Installation | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| It is possible to enable SSO for an existing Central installation, even if the installation has existing users. Follow the instructions above to enable SSO. Because Central identifies users by their email address, the email address associated with a Central account must match the address in the identity provider. If the email address does not match, the user will not be able to log in. |
There was a problem hiding this comment.
I think this is all true. We've been able to toggle SSO on and off on dev servers. There was related discussion at getodk/central-backend#910 (comment) that wasn't fully resolved. However, I understand the flow better now than when I left those comments.
|
|
||
| TODO Setting up the identity provider | ||
|
|
||
| TODO Google Chrome profiles |
There was a problem hiding this comment.
This TODO is related to the discussion here: getodk/central#449 (comment). It was also discussed in Slack. I added some notes to the brainstorming doc drawing from Slack:
If you want to go between Central accounts when using Chrome and Google as the IdP you have to use separate browser profiles. Weirdness around when the browser uses the same identity provider.
I didn't completely follow that discussion at the time. @lognaturel, would you mind adding docs about this case?
| Disabling SSO | ||
| ~~~~~~~~~~~~~ | ||
|
|
||
| It is possible to disable SSO by following the steps below. If there were users before SSO was enabled (if SSO was disabled, then enabled, then disabled again), users will be able to log into Central using their same password from before SSO was enabled. You can :ref:`reset users' passwords <central-users-web-reset-password>` after disabling SSO. |
There was a problem hiding this comment.
Rather than disabling SSO, could they use the command line to create a new Central administrator with the correct email address?
There was a problem hiding this comment.
Yes, true. Might be clearer to change it.
|
|
||
| Central is not compatible with every identity provider. Central uses the OpenID Connect (OIDC) protocol. When SSO is enabled in Central, Central does not manage passwords, but it still identifies users using their email address. Central assumes that the identity provider verifies email addresses, requiring users to prove ownership of the email address they specify. If that is not the case, then do not enable SSO in Central. | ||
|
|
||
| If SSO is enabled, some features in Central will stop working. OData feeds will not be accessible in tools like Power BI or Excel. The API will not be available, which means that pyODK and ruODK will not be able to fetch data from Central. In the future, we hope to provide a way to access OData and the API when SSO is enabled. |
There was a problem hiding this comment.
I think we've tried to move away from "in the future" types of statements. Could we instead say "Currently, OData feeds..."
|
|
||
| If SSO is enabled, some features in Central will stop working. OData feeds will not be accessible in tools like Power BI or Excel. The API will not be available, which means that pyODK and ruODK will not be able to fetch data from Central. In the future, we hope to provide a way to access OData and the API when SSO is enabled. | ||
|
|
||
| To enable SSO in Central, you will need to provide information from your identity provider, specifically the issuer URL, client ID, and client secret. If you use Google Workspace or Azure Active Directory, you can follow the instructions below to find this information. |
There was a problem hiding this comment.
Let's add these sections as part of a separate PR after release as you suggest below.
|
The more I think about this, the less I like it being in the Digital Ocean install instructions. Mostly this is just helpful information about how Single Sign-On works that any user would benefit from. How about making it its own page? |
|
Continued in #1661 |
Closes #1633.