What is iframe auth?
With iframe auth you can use your own authentication page/API to log in users on pimentaCHAT.
When enabled pimentaCHAT first do an XMLHttpRequest to the iFrame API URL trying to see if the user is already logged in at the third party website. If that doesn’t succeed then pimentaCHAT will present the Iframe URL within an iframe, so the user logs in on the third party website which means he is authenticated on pimentaCHAT as well.
We have developed an example app written in NodeJS in order to help you understanding this authentication flow. Please take a look at iFrame Auth Example
Configuring
API URL and API Method
Configure how pimentaCHAT will call the third party system to either login or to verify if the user is already logged in, by setting API URL and API Method fields.
API URL refers to endpoint on the third-party system that will check if the user is already logged in to that system. The API Method is used to select the submission method pimentaCHAT will use to submit information to the API URL (for instance using POST).
If the user has already logged into the third-party system, the API URL should communicate to pimentaCHAT and return a JSON object containing either a token or loginToken property, otherwise (if the user is not already logged in) the API URL should return an empty body with status 401.
The choice of which property API URL will return depends on how the third-party system decides to interface back with pimentaCHAT, as described in one of the two ways below:
Using pimentaCHAT API
If you have the user’s password stored (or it is the same between your third party system and pimentaCHAT), you can use pimentaCHAT’s REST APIs to log in the user, this way you will get an authToken back from pimentaCHAT that should be returned as loginToken by your endpoint.
At this point, if the user does not have a pimentaCHAT account yet, you can either use pimentaCHAT API to create an user using a admin account or register him.
After you log the user in, you should return a payload like the following:
{
"loginToken": "already-saved-or-returned-login-token"
}
Managing MongoDB directly
In the case you have access to pimentaCHAT’s database, you can connect there directly and manage the user record by yourself. This might be useful if you have MongoDB on your stack already and don’t want to learn pimentaCHAT’s API.
To do so the endpoint should connect on pimentaCHAT’s MongoDB database and make sure the generated-token is saved on users collection on the corresponding user record. The generated-token should be saved on the field path services.iframe.token. This is how the user record should look like:
{
"_id": "MZiFvWAf96876875u",
"createdAt": new Date(1432252673528),
"services": {
"iframe": {
"token": "generated-token"
}
},
"emails": [
{
"address": "useremail@gmail.com",
"verified": true
}
],
"name": "John Doe",
"username": "john.doe",
"active": true,
"statusDefault": "online",
"roles": [
"user"
],
"type": "user"
}
On this case, the response should be:
{
"token": "generated-token"
}
IFrame URL
The URL of the page you want to show as the login page of your pimentaCHAT instance (this page can be created in any programming language and/or web framework).
The login page will then communicate back to pimentaCHAT using postMessage API.
After user logs in, you have to authenticate him on pimentaCHAT side, pretty much the same as you did before on API URL endpoint, but now you should return a JavaScript code that will be rendered within the iframe, depending how you logged in the user:
- If have used pimentaCHAT’s APIs to log in the user or already have user’s token saved in your end, return:
<script>
window.parent.postMessage({
event: 'login-with-token',
loginToken: 'your-token'
}, 'http://your.pimenta.chat.url');
</script>
- If you have saved user’s token connecting directly to pimentaCHAT’s database on the user’s field
services.iframe.token:
<script>
window.parent.postMessage({
event: 'try-iframe-login'
}, 'http://your.pimenta.chat.url');
</script>
Using OAuth configured on pimentaCHAT’s end
If you have OAuth services configured on pimentaCHAT, you can trigger them from within your login page as well.
To implement this authentication, after triggering the OAuth authentication you will receive a postMessage back from pimentaCHAT with user’s credentials response from OAuth service. You need to manage the user creation/authentication on pimentaCHAT’s database by yourself, the same as described earlier.
window.parent.postMessage({
event: 'call-facebook-login',
permissions: ['email']
}, 'http://your.pimenta.chat.url');
The reply will be a postMessage back to your page with:
{
event: 'facebook-login-success',
response: {
// authResponse: Object
// accessToken: "a7s6d8a76s8d7..."
// expiresIn: "5172793"
// secret: "..."
// session_key: true
// sig: "..."
// userID: "675676576"
// status: "connected"
}
}
Or an error
{
event: 'facebook-login-error',
error: error,
response: response
}
window.parent.postMessage({
event: 'call-google-login',
// scopes:
// webClientId:
}, 'http://your.pimenta.chat.url');
The reply will be a postMessage back to your page with:
{
event: 'google-login-success',
response: {
// "email": "albert-einstein-example@gmail.com",
// "userId": "1082039180239",
// "displayName": "Albert Einstein",
// "gender": "male",
// "imageUrl": "https://lh5.googleusercontent.com/-shUpniJA480/AAAAAAAAAAI/AAAAAAAAAqY/_B8oyS8yBw0/photo.jpg?sz=50",
// "givenName": "Albert",
// "familyName": "Einstein",
// "ageRangeMin": 21,
// "oauthToken": "123198273kajhsdh1892h"
}
}
Or an error
{
event: 'google-login-error',
error: error
}
window.parent.postMessage({
event: 'call-twitter-login'
}, 'http://your.pimenta.chat.url');
The reply will be a postMessage back to your page with:
{
event: 'twitter-login-success',
response: {
// "userName": "orodrigok",
// "userId": 293123,
// "secret": "asdua09sud",
// "token": "2jh3k1j2h3"
}
}
Or an error
{
event: 'twitter-login-error',
error: error
}
How to login in pimentaCHAT with default account system while in development
When you activate the IFrame auth you will not be able to access pimentaCHAT’s default login page, however if still need/want to use your pimentaCHAT’s credentials to log in, you can do that by opening the browser’s Developer Console and executing the following code:
Meteor.loginWithPassword('username-or-email', 'your-password');
