Augmenting Realty RETS protocol with vendor extensions – OAUTH AS STS issued RSA-signed JWTs shows an IETF internet-draft document on the topic of what in realty we would call a rets client talking to a RETS data server login endpoint in order to retrieve such as a MLS member record (or listings). Traditionally, data consumer using RETS client software are issued device/vendor credentials, including passwords and/or RSA signing keys. The vendor record stores the “scopes” that limit what their RETS client can do, having used the login endpoint to get a session-token. The login response message turns the scopes into a list of “capability” URLs on which are activated various data-providing endpoints. If the vendor uses the login transaction to get the session-token and the list of scope/URLs for the session-token, the RETS client software will thereafter present the session-token to the data-service endpoint along with a data request – to retrieve some specified set of entity instances (in XML or some other data format). Typically a browsing-user goes to a VAR site for the MLS – a site built using a webapp which builds-in the data-service-consuming features of the vendor’s RETS Client (as above). Typically, the webapp merges the data with other data sources and presents an enhanced view of the realty data. One incarnation of the webapp would be an Office365 share point website into which the vendor’s “Sharepoint App” has been registered, and whose implementing website has embedded RETS client software and credentials.

OK. All the above is ancient history, deployed globally, and old-hat technologically. So let’s overlay all the new terminology of OAUTH 2.0 so RETS gets a new coat of IETF-colored paint.

The resource “owner” is an MLS member (with a member record…and listing records).

The resource “server” is the set of post-login endpoints exposed by the RETS server, by MLS tenant

The OAUTH “client” is the vendor using RETS client software to pull data, server to server. The OAUTH client has vendorid/vendorpassword and optional RSA signing key.

The STS component of the OAUTH AS (authorization server) is the RETS Login transaction (a realty-specific interface for issuing access-tokens known as lists of capability URLs).

Assume PingFederate is the OAUTH AS, configured to perform the authorization_code authorization grant use cases. The vendor’s webapp invokes the OAUTH AS managed process when the Realtor first visits the webapp (with embedded RETS client). A “persistent grant” of authority is stored by the OAUTH AS recording the individual Realtor’s “Consent” for the vendor of the webapp to use the server-server RETS client data-channel’s “capabilities” (once obtained). If the grant is revoked, or expires, or is otherwise terminated, the vendor’s webapp would normally perform the authorization_code use case again. As the first time, the Realtor will authentication (using websso) and issue consent. In the sharepoint 2013 incarnation, having obtained access to sharepoint list data as consequence of being launched as a “SharePoint App”, the vendors webapp will then use the process described to get authority to access the RETS data, allowing the app to present an enhanced view of both data sets.

The RETS protocol already features both channel-specific and URI-resource specific security mechanisms – making sophisticated use of digest authentication standard. It also leverages a session-token (whose integrity and legitimate use on particular channel instances is secured by means of specific digest authentication countermeasures).

Logically, once the vendor webapp has received the  authorization_code it SHOULD perform within 60s a RETS login transaction, citing the code in an RETS HTTP request extension header along with vendorid/password and RSA signature (in a second RETS HTTP Request extension header). The RETS login response will contain an additional vendor-specific extension field – bearing the RSA_signed JWT issued by the PingFederate OAUTH AS STS component in response to a request made by the RETS login service and which response is consume by the login service and inserted in RETS login response extension header.

No presentation of the signed JWT will be made by RETS Client. However, vendors are required to store the tokens, for audit purposes. Being signed with an asymmetric key, the vendor will be unable to forge the token, during its intended lifetime. Should any dispute being initiated  against the vendor for failing to respect the limits of the MLS data consumer contract on behalf of the data owner (MLS) or the individual Realtor, the vendor has evidence to show compliance and authority to consume data on particular URIs. Failure to present an JWT that shows authority to use endpoints and data for the particular facts of the dispute can be assumed to be evidence of non-compliance.

The scheme needs no inter-vendor agreement, being within the scope of existing per-vendor extension frameworks known to work in the field. The scheme can easily be extended to a multiple-vendor environment, with suitable cooperation.

Now, this description does not yet envision the client replacing the RSA signature on the RETS Login request with a SAML assertion. Since the RSA signature is already an vendor-extension field, one can similarly extend the client’s RETS login request with a SAML assertion.

Concerning implementation, we see from the IETF document


Using PingFederate’s existing capabilities, we could require RETS vendors to themselves signup or renew their authority by (i) completing conventional ws-fedp websso from an MLS IDP to the PingFederate OAUTH AS configure NOT to present a consent screen, (ii) presenting the authorization_code obtained from Realtor enrollment (which implies that a Realtor has been through a websso and consent process, too), and (iii) cite the access_token in the RETS login header (rather than the assertion or the RSA signature).

As we already saw featured in Azure AD demos requiring the tenant administrator to “admit” a particular third party webapp (SP) into the site-users’ experience, we see here the OAUTH-version of the infrastructure for vendor apps to be so authorized. We see this process then being extended to link up with the individual user’s authorization grant (communication by the authorization_code mechanism). The web app thus has authority from the site into which it is now a component part and authority to present particular user data from a realty data service.

About home_pw

Computer Programmer who often does network administration with focus on security servers. Sometimes plays at slot machine programming.
This entry was posted in oauth, RETS. Bookmark the permalink.