SSO is primarily for improving prospects' experience with respect to self showing and can be adopted by the Enterprise Clients, who uses iframe experience. Specifically for the clients using popup option using schedule_embed endpoint.
Example: https://secure.rently.com/properties/schedule_embed?uid=2&name=21438
If clients have a logged In prospect, then prospects do not need to provide their information again in Rently’s SGT workflow. Client need to just pass JWT signed token for passing the prospect’s information from their site to Rently iframe.
Token Specification:
Type: JWT signed token
Token Contents (keys): first_name, last_name, email, phone, verified_phone (value: true/false)
verified_phone field is to check if phone verification (e.g., OTP) is already conducted on client’s end. If so, this confirmation can be included in the JWT token payload, which would allow us to skip the OTP verification step on our side, further simplifying the self showing process.
Signed Token: Please use asymmetric signing (e.g., RS256), which involves signing the JWT with a private key and verifying it using a corresponding public key.
To facilitate verification, we kindly request the public key and the algorithm information. Ideally, clients could provide an endpoint to serve the public key in JWK format ref. https://datatracker.ietf.org/doc/html/rfc7517 (example JWK format is mentioned below), allowing Rently to automatically retrieve updated public keys when clients rotates the signing key, without needing additional communication.
{"keys":
[
{"alg":"EC",
"crv":"P-256",
"x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
"y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
"use":"enc",
"kid":"1"},
{"alg":"RSA",
"mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"exp":"AQAB",
"kid":"2011-04-29"}
]
}
Token communication between Client’s site and Rently’s site :
Option 1: This token needs to be passed from Client’s site to Rently’s iframe . Please use https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage for secure communication.
When rently’s iframe would be loaded in client’s site, it will trigger a postMessage event, for informing the client that it is ready to accept the token.
PostMessage Sample Code Snippet:
// Listen for the response from the client's site
<script>
// Reference to the iframe element
let iframe;
// Listen for messages from the iframe
window.addEventListener('message', function(event) {
console.log("Received message from child iframe:", event.data);
if (event.data.type === 'ready_for_auth') {
iframe.contentWindow.postMessage({event: 'auth', type: 'token', authToken: 'TOKEN'}, ORIGIN);
// ORIGIN value: Production - https://homes.rently.com
// ORIGIN value: Rently Sandbox - https://homes.rentlyatlas.com
};
});
// Set up the iframe after the page loads
window.onload = function() {
iframe = document.getElementById('childIframe');
};
</script>
This is a sample code, production code may vary a little based on client’s site configuration. We recommend a sandbox testing before going live in production.
Option 2: In the scenario of redirection instead of iframe, jwt token can be passed in the url params. Please ensure the total URL length is below browser and server limits.
Example URL:
https://secure.rently.com/properties/schedule_embed?authToken=yourJWTtoken&uid=companyID&name=propertyID
The security is ensured by generating a short lived token on our side.
In case of token being passed in url params, we recommend to use short lived token.