dev/core#2141 - Add "oauth-client" extension (hidden)

[totten]

Overview

This adds the oauth-client extension for connecting to OAuth2-based web-services. It includes data-storage, APIs, and UIs for working with client-credentials and persistent tokens. It implements key elements from the design in https://lab.civicrm.org/dev/core/-/issues/2141.

(NOTE: This PR only adds the extension. The hard pre-requisites for oauth-client have already been merged into civicrm-core. However, there are some open PRs with soft-requirements that improve debugging. For a full branch with all recommended patches, see #18863.)

Use-case: Add an IMAP-OAuth client

• Enable the hidden extension oauth-client.
  • Ex: cv en oauth_client
• Register the CiviCRM site as a client for an OAuth2-based service
  • Navigate to "Administer => System Settings => OAuth" (civicrm/admin/oath).
  • Choose the relevant web-service provider (e.g. gmail or ms-exchange).
  • This will open a page like:
    
  • Keep that page open. In another tab, use the manual for Google OAuth2 / IMAP or Microsoft OAuth2 / IMAP to register a client with them. As necessary, drill-down on related links/pre-reqs. (The aim is to provide more tuned sysadmin instructions, but these should be workable in a pinch.)
  • Return an the CiviCRM admin page. Paste the credentials and finish registering the client.
• Add a mail account for the service
  • Navigate to "Administer => CiviMail => Mail Accounts" (civicrm/admin/mailSettings)
  • Under "Add Mail Account", you will see an option for Google or Microsoft. Click it.
    
  • The browser will redirect to the Google or Microsoft login screen. Choose the desired account and approve access.
  • The browser will redirect back to CiviCRM. You will see "Edit Mail Account" with some defaults pre-populated. (Note: You can ignore "Password". Also, note that I've only been testing the authentication. So other options like "Localpart" or "Used For?" should still be configured to taste.)
    
  • Click "Save & Test".
  • As per dev/mail#2141 - MailSettings - Add button+API for testing a connection #18911, this may return success or failure.
• Optionally, return to "OAuth" admin screen to see the changes.
  • Navigate to "Administer => System Settings => OAuth" (civicrm/admin/oath).
  • Choose the relevant web-service provider (e.g. gmail or ms-exchange).
  • In the first tab, the "Tokens" table now has data:
    

Technical Details

• There are two new permissions:
  • manage OAuth client: Provides access to register clients and request tokens.
  • manage OAuth client secrets: Provides raw access to sensitive tokens which are otherwise invisible.
• The providers mentioned above (gmail, ms-exchange, etc) are defined in ext/oauth-client/providers/*.json. The list can be manipulated via hook_civicrm_oauthProviders. It is consumed via APIv4's OAuthProvider.get.
• When you register a "Client ID" and "Client Secret", it creates a new record in civicrm_oauth_client (OAuthClient).
• When you add a mail account, it creates a new record in civicrm_mail_settings (MailSettings) and a linked record in civicrm_oauth_systoken (OAuthSysToken).

Comments

• If activating the extension on an older version of cv, it may not accept the dash in oauth-client, but it will accept an underscore oauth_client.
• In the exploratory branch, I have some draft comments which will be the seed for more detailed r-docs.

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[eileenmcnaughton]

This code is entirely within the oauth extension. As discussed on chat the final review point for this is where we unhide this. We have discussed the appropriateness for core & general approach previously and that is generally agreed.

So the bar for this checkpoint is - nothing alarming or unexpected in there & suitable test cover. I'm comfortable with those so merging.

For the next save-point the bar is that the documentation is sorted & we get some r-run confirmation - preferably on live sites - that would be the point we unhide it