Adding documentation on how to use OIDC

Author: davidpcls

docs/source/configuration.rst

@@ -294,6 +294,85 @@ See the documentation on ``LDAPAuthenticator`` for more details.
 
     authenticators.LDAPAuthenticator
 
+OIDC Authenticator
+++++++++++++++++++
+
+``OIDCAuthenticator`` integrates the server with third-party OpenID Connect providers
+such as Google, Microsoft Entra ID, ORCID and others. The server does not process user
+passwords directly: authentication is delegated to the provider and the server validates
+the returned OIDC token.
+
+General setup steps:
+
+#. Register an application with the OIDC provider.
+#. Configure redirect URIs for the provider application. For provider name ``entra`` and
+   host ``https://your-server.example`` the redirect URIs are:
+
+   - ``https://your-server.example/api/auth/provider/entra/code``
+   - ``https://your-server.example/api/auth/provider/entra/device_code``
+
+#. Store the client secret in environment variable and reference it in config.
+#. Use provider's ``.well-known/openid-configuration`` URL.
+
+Typical ``well_known_uri`` values:
+
+- Google: ``https://accounts.google.com/.well-known/openid-configuration``
+- Microsoft Entra ID: ``https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration``
+- ORCID: ``https://orcid.org/.well-known/openid-configuration``
+
+Example configuration (Microsoft Entra ID)::
+
+    authentication:
+      providers:
+        - provider: entra
+          authenticator: bluesky_httpserver.authenticators:OIDCAuthenticator
+          args:
+            audience: 00000000-0000-0000-0000-000000000000
+            client_id: 00000000-0000-0000-0000-000000000000
+            client_secret: ${BSKY_ENTRA_SECRET}
+            well_known_uri: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
+            confirmation_message: "You have logged in successfully."
+    api_access:
+      policy: bluesky_httpserver.authorization:DictionaryAPIAccessControl
+      args:
+        users:
+          <login-name>:
+            roles:
+              - admin
+              - expert
+
+Example configuration (Google)::
+
+    authentication:
+      providers:
+        - provider: google
+          authenticator: bluesky_httpserver.authenticators:OIDCAuthenticator
+          args:
+            audience: <google-client-id>
+            client_id: <google-client-id>
+            client_secret: ${BSKY_GOOGLE_SECRET}
+            well_known_uri: https://accounts.google.com/.well-known/openid-configuration
+    api_access:
+      policy: bluesky_httpserver.authorization:DictionaryAPIAccessControl
+      args:
+        users:
+          <login-name>:
+            roles: user
+
+.. note::
+
+    The name used in ``api_access/args/users`` must match the identity string produced by
+    the authenticator for your provider configuration. Verify with ``/api/auth/whoami`` after
+    successful login.
+
+See the documentation on ``OIDCAuthenticator`` for parameter details.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: generated
+
+    authenticators.OIDCAuthenticator
+
 
 Expiration Time for Tokens and Sessions
 +++++++++++++++++++++++++++++++++++++++

docs/source/usage.rst

@@ -154,6 +154,49 @@ Then users ``bob``, ``alice`` and ``tom`` can log into the server as ::
 
 If authentication is successful, then the server returns access and refresh tokens.
 
+Logging in with OIDC Providers (Google, Entra, ORCID, ...)
+-----------------------------------------------------------
+
+For providers configured with ``OIDCAuthenticator``, use provider-specific endpoints
+under ``/api/auth/provider/<provider-name>/...``.
+
+Browser-first flow
+++++++++++++++++++
+
+If you are already in a browser context, open:
+
+``<hostname>/api/auth/provider/<provider-name>/authorize``
+
+This redirects to the OIDC provider login page and then back to the server callback.
+
+CLI/device flow
++++++++++++++++
+
+For terminal clients, start with ``POST /api/auth/provider/<provider-name>/authorize``.
+The response includes:
+
+- ``authorization_uri``: open this URL in a browser
+- ``verification_uri``: polling endpoint for the terminal client
+- ``device_code`` and ``interval``: values for polling
+
+Example using ``httpie`` (provider ``entra``)::
+
+  http POST http://localhost:60610/api/auth/provider/entra/authorize
+
+After opening ``authorization_uri`` in a browser and completing provider login,
+poll ``verification_uri`` using ``device_code`` until tokens are issued::
+
+  http POST http://localhost:60610/api/auth/provider/entra/token \
+    device_code='<device_code_from_authorize_response>'
+
+When authorization is still pending, the endpoint returns ``authorization_pending``.
+When complete, it returns access and refresh tokens.
+
+.. note::
+
+    In common same-device flows the callback can complete automatically without manually
+    typing the user code. Manual code entry remains available as a fallback path.
+
 Generating API Keys
 -------------------