Merge pull request #12865 from nextcloud/enh/noid/oidc-admin-dev

Add small Oidc sections in admin and developer docs

Author: julien-nc

admin_manual/configuration_user/index.rst

@@ -16,3 +16,4 @@ User management
     user_auth_ldap_api
     user_provisioning_api
     profile_configuration
+    user_auth_oidc

admin_manual/configuration_user/user_auth_oidc.rst

@@ -0,0 +1,40 @@
+=======================================
+User authentication with OpenID Connect
+=======================================
+
+Nextcloud users can authenticate via an external identity provider.
+Nextcloud can also be an identity provider itself.
+
+Authentication in Nextcloud
+---------------------------
+
+The `OpenID Connect user backend app <https://apps.nextcloud.com/apps/user_oidc>`_ makes it possible for users to
+authenticate using external Oidc identity providers.
+
+This app can optionally be in charge of user provisioning (by creating users when they first connect) or rely on
+other user backends and only take care of authentication.
+
+`More details in the project's README <https://github.com/nextcloud/user_oidc#user_oidc>`_
+
+Using Nextcloud as an identity provider
+---------------------------------------
+
+The `OIDC Identity Provider community app <https://apps.nextcloud.com/apps/oidc>`_
+can be installed to make Nextcloud an identity provider for other services.
+
+This app will allow any Nextcloud user (managed by any user backend) to authenticate during an Oidc login flow.
+This is useful if you want your Nextcloud instance to be the authority regarding authentication and user profile data
+among multiple services.
+
+Bearer token validation
+-----------------------
+
+Nextcloud can accept Oidc ID tokens and access tokens as valid bearer token for API requests.
+If using an external identity provider, only the ``user_oidc`` app is necessary.
+
+If Nextcloud is the identity provider, you will naturally need the ``oidc`` app to make Nextcloud an Oidc provider,
+and also the ``user_oidc`` app because it will take care of validating API requests authentication.
+In user_oidc, the ``oidc_provider_bearer_validation`` config flag needs to be set to true so ``user_oidc`` knows
+it needs to ask the ``oidc`` app to validate the received bearer tokens.
+
+`More details on bearer token validation <https://github.com/nextcloud/user_oidc#bearer-token-validation>`_

developer_manual/digging_deeper/index.rst

@@ -21,6 +21,7 @@ Digging deeper
    flow
    npm
    notifications
+   oidc
    out_of_office
    performance
    phonenumberutil
@@ -44,6 +45,6 @@ Digging deeper
    two-factor-provider
    status
    user_migration
-   users    
+   users
    web_host_metadata
    time

developer_manual/digging_deeper/oidc.rst

@@ -0,0 +1,33 @@
+=====================
+OpenID Connect (Oidc)
+=====================
+
+There are multiple ways for apps to interact with the ``user_oidc`` and ``oidc`` apps.
+It is possible to get tokens from those apps and to ask them to validate tokens.
+All available events are in the ``user_oidc`` app even if some use case don't involve the main feature of this app.
+
+`user_oidc events doc <https://github.com/nextcloud/user_oidc/tree/main/docs>`_
+
+Getting the login token
+-----------------------
+
+When using ``user_oidc``, which uses an external identity provider, the login token can be stored so apps can later
+get it via an event.
+
+The ``store_login_token`` config flag must be enabled.
+The login token is automatically refreshed by ``user_oidc`` when needed during the user session.
+The login token can be obtained by apps by emitting the ``OCA\UserOIDC\Event\ExternalTokenRequestedEvent`` event.
+
+Token exchange
+--------------
+
+If the external identity provider supports token exchange, apps can ask ``user_oidc`` to perform one
+and deliver the exchanged token by emitting the ``OCA\UserOIDC\Event\ExchangedTokenRequestedEvent`` event.
+
+Generating a token if Nextcloud is the provider
+-----------------------------------------------
+
+If the ``oidc`` app is used to make Nextcloud an identity provider, some Nextcloud apps might need to ask
+Nextcloud to generate a token that they will use to authenticate against an external service.
+This requires both ``oidc`` and ``user_oidc`` apps installed (even if ``user_oidc`` is not used as a user backend).
+The token can be generated by emitting the ``OCA\UserOIDC\Event\InternalTokenRequestedEvent`` event.