API: Add support for OAuth2 Client Credentials and Access Tokens

[lastzero]

External applications must be able to authenticate with OAuth2 Client Credentials in order to obtain valid Access Tokens for communication with our REST API.

Further OAuth2 use cases and authentication options are beyond the scope of this issue. They may be added over time after this has been implemented.

Acceptance Criteria:

• In addition to (a) implementing a POST /api/v1/oauth/token endpoint for creating access tokens, this includes (b) adding support for standard Bearer Token authentication headers and (c) a minimum of scope-based authorization checks.
• As a first step, Prometheus should be able to query the GET /api/v1/metrics endpoint with authentication so that it won't need to be publicly accessible: API: Expose Prometheus-style metrics endpoint #3730
• Helpful implementation details and usage examples should be added to the docs, so developers understand the authentication options and know how to use the API: https://docs.photoprism.app/developer-guide/

Related Issues:

• API: Expose Prometheus-style metrics endpoint #3730
• Metrics: Add a Prometheus-compatible API endpoint #213
• Account: Add Support for 2-Factor Authentication #808
• Auth: Add support for single sign-on via OpenID Connect (OIDC) #782
• Auth: Add authorize API endpoint to implement the authorization code flow #4368
• Auth: Add userinfo API endpoint to get information about the logged in user #4369
• Sharing: Multi-user / multi-library support with private and shared photos/albums #98

Protocol References:

• https://prometheus.io/docs/prometheus/latest/configuration/configuration/#oauth2
• https://www.scottbrady91.com/oauth/client-authentication#:~:text=OAuth%20client%20secrets
• https://www.scottbrady91.com/oauth/oauth-is-not-user-authorization
• https://www.oauth.com/oauth2-servers/access-tokens/refreshing-access-tokens/
• https://www.oauth.com/oauth2-servers/access-tokens/access-token-lifetime/
• https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/
• https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/
• https://learn.microsoft.com/en-us/linkedin/shared/authentication/programmatic-refresh-tokens
• https://oauth.net/2/grant-types/client-credentials/
• https://oauth.net/2/scope/
• https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
• https://auth0.com/docs/get-started/authentication-and-authorization-flow/call-your-api-using-the-client-credentials-flow#example-post-to-token-url
• https://auth0.com/intro-to-iam/what-is-oauth-2
• https://auth0.com/docs/authenticate/protocols/oauth
• https://auth0.com/docs/secure/tokens/id-tokens/id-token-structure
• https://auth0.com/docs/authenticate/protocols/openid-connect-protocol
• https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2#grant-type-client-credentials
• https://aaronparecki.com/oauth-2-simplified/
• https://rclone.org/webdav/
• https://owncloud.dev/clients/rclone/webdav-sync-oidc/
• https://www.webdavsystem.com/server/documentation/choosing_authentication/
• http://www.webdav.org/specs/rfc2617.html#rfc.section.4.1
• https://frontegg.com/blog/oauth-grant-types

Authentication Libraries:

• https://github.com/zitadel/oidc
• https://pkg.go.dev/golang.org/x/oauth2
• https://pkg.go.dev/golang.org/x/oauth2/jwt
• https://github.com/go-oauth2/oauth2
• https://github.com/pquerna/otp

Documentation Examples:

• https://docs.semui.co/administration-guide/openid
• https://api.stackexchange.com/docs/authentication
• https://dev.fitbit.com/build/reference/web-api/developer-guide/authorization/
• https://cloudentity.com/developers/basics/oauth-client-authentication/client-secret-authentication/
• https://developer.okta.com/docs/reference/api/oidc/#get-started
• https://www.authelia.com/configuration/identity-providers/open-id-connect/
• https://goauthentik.io/integrations/sources/oauth/#openid-connect
• https://developers.google.com/identity/openid-connect/openid-connect
• https://connect2id.com/products/server/docs/api
• https://connect2id.com/products/server/docs/api/discovery
• https://connect2id.com/products/server/docs/api/authorization
• https://connect2id.com/products/server/docs/api/token
• https://www.zoho.com/accounts/protocol/oauth/token-limits.html
• https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods
• https://help.akana.com/content/current/cm/api_oauth/oauth_oauth20/m_oauth20_getTokenPOST.htm
• https://help.akana.com/content/current/cm/api_oauth/aaref/Ref_Values.htm#values_oauthgranttypes

[lastzero]

I will push my changes and provide an updated preview build for testing as soon as the new CLI commands (almost done) and the scope-based authorization checks are implemented, so probably early next week :)

[lastzero]

My last commit adds standard OAuth2 client credentials and bearer token support as well as scope-based authorization checks for REST API clients:

• Note that this first implementation should not be used in production and that the optional access token limit has not been implemented yet.
• If you would like to test these changes without building from source, you can use the photoprism/photoprism:test image available on Docker Hub: https://hub.docker.com/r/photoprism/photoprism/tags?page=1&name=test
• Use the photoprism clients CLI subcommands to list, create, update and delete clients and then test the credentials e.g. with the new GET /api/v1/metrics endpoint. The required scope for this is "metrics", but the "*" setting should also work.

[lastzero]

Here's what I think is still needed to make this releasable:

• The ability to use client authentication with a bearer token header for WebDAV access too
• Enforcement of the Access Token limit, so that clients cannot create as many tokens as they like
• Add /.well-known/ endpoints for automatic client configuration
• Helpful documentation with implementation details and usage examples
• A little more time so it can be tested in a variety of scenarios, e.g. together with 2FA

[brandon1024]

I'll happily take on documentation tasks related to the setup of prometheus :-)

[lastzero]

If you would like to test the new POST /api/v1/oauth/token endpoint, you can use the photoprism/photoprism:test image available on Docker Hub and, for example, run this in a terminal to create a new access token:

curl -Ss -X POST http://localhost:2342/api/v1/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=metrics&client_id=ID&client_secret=SECRET'

Simply replace ID and SECRET with the actual client ID and secret created using the new photoprism clients add command and make sure the base URL is correct, i.e. you may also need to change http://localhost:2342/.