What is a broker?
A broker is a registry of applications used to kickstart initial connections between applications and sites. Applications only need to register once for all sites that recognise the broker.
Sites can recognise as many or as little brokers as they want. This site is the default central repository for the OAuth plugin, however site administrators can register additional brokers, or remove the default broker. For example, a corporate network of sites may wish to run its own broker for internal applications, or you may wish to run a broker locally to test the process.
OAuth client applications can also continue to be registered directly with the site; the broker process is built on top of the OAuth flow, but is not required for applications to work.
How does the process work?
- Application developers register their application with the central registry.
- When a user wants to connect the application to their site, the application asks the broker to start the process.
- The broker asks the site to register the application, and vouches for the application.
- The site registers the application and issues credentials (client key and secret), then passes them to the broker, while also double-checking the request is valid.
- The broker confirms the request is valid, then passes the credentials back to the application.
- The application now follows the usual OAuth authorisation process with the site using the new credentials.
After the connection is made, the broker is no longer necessary, and all future communication with the site can be direct.
Why is a broker necessary?
WordPress sites can be installed anywhere, which makes the usual OAuth process a little unwieldy. This is different to most REST APIs, which are built for services instead, allowing easy central control. Without a centralised registry of applications, site administrators would have to register applications manually on a per-site basis. This isn’t a great user experience, and requires administrators to handle registering every new application manually.
Security concerns are harder to handle with per-site registration. If an application is compromised, the scope for damage is huge, without any way to disable the compromised application across all sites.
A centralised repository allows solving these issues. Applications can register once with the central repository, then work automatically across all sites. If the application is compromised, the credentials can be revoked across all sites using it.
The broker process allows creating this centralised repository while keeping the system secure and private. The broker never touches user credentials through the process.
How secure is the process?
The broker process is specifically designed to provide a robust security solution for decentralised authentication. Since it’s not possible to ensure every site has HTTPS, the process instead involves a checking process with the broker, which is required to have HTTPS.
After receiving a connection request, the site optimistically generates client credentials, but does not immediately activate them. These credentials are then sent to the broker that requested them over HTTPS using a POST request, and only after the broker has confirmed the connection request is legitimate, the credentials are then made active. This significantly increases security, as the HTTPS request is much harder to execute a man-in-the-middle attack on.
The security of the confirmation request could be compromised, however this would require the man-in-the-middle attacker to have an SSL certificate that the site believes is valid. This is hard to execute, but could be possible via a certificate authority error, OpenSSL exploit, or compromised root certificates on the site. These are hard to exploit, and outside the scope of the broker process; they are a compromise of the server itself instead.
Sites without the capability to send HTTPS requests cannot participate in the broker process. As the security of the system is built on the security of SSL/TLS, these sites would be fundamentally insecure. Applications which want to access these sites should allow users to manually register client applications.
We take the security of the broker system very seriously. Contact us immediately via HackerOne if you believe you have an exploit which compromises the security of the system in any way. We appreciate responsible disclosure.
How does this affect my privacy?
The process is designed to ensure you retain control of your data. While it is unavoidable that the application credentials pass through the broker, the broker is designed to avoid storing these credentials once the process is complete. Additionally, user credentials never pass through the broker, as the OAuth authorisation process occurs separately.
Theoretical privacy concerns do exist. Because the client credentials pass through the broker, a vulnerability in the broker or malicious broker could store these for later replay attacks. This allows the broker to imitate the application and allows potential phishing attacks. User credentials always require user interaction (and cookie verification), but the possibility for the broker to gain these does exist. To mitigate this scenario, the reference broker (and broker running this site) does not store credentials after the process has been completed. This partially mitigates the issue, but the system inherently involves trusting the broker, so the issue is not possible to fully remove.
You can disable the broker at any time by filtering
rest_broker_known_brokers and removing the default broker. You can also run your own broker by running the Broker Authentication plugin on your site (and optionally, this theme).