1 A SSO, what for?
SSO allows for users to launch your application from a platform's dashboard without having to type in credentials. This enhances the user experience of customers by skipping a step to access your app.
2 What is supposed to happen when a user launches my application for the first time from his dashboard?
When accessing your application for the first time, a new account must be created based on the user details including first and last name, email, company name etc... You may have different subscription plans to be offered to the user. The recommended approach is to setup the user account under a free trial if you support this kind of subscription. Otherwise it is recommended to provide the user with a basic subscription plan so he can try out your application functionalities. After the free trial has expired, the user will be charged via the billing API.
As part of the SSO process, the user details are passed on (first and last names, email). You can decide to use these to match the user against an existing user inside your application rather than creating a new account. This will give the end user a better user experience.
3 What is the Workflow?
The Single Sign On process is initiated from one of the platforms performed by Maestrano, when a user clicks on your application from his dashboard. This redirects the user to the configured SSO initialization endpoint which then redirects back to the marketplace IDM endpoint. The user is then redirected to your SSO consume endpoint with all the User details required to either log the user in or create a new account.
The SSO Init Path and Consume Path are configured in the developer platform per environment in the technical section.
These path should contains a variable that will indicate the marketplace, the endpoint then will retrieve the marketplace variable from the url.
For example in our java demo application (https://github.com/maestrano/demoapp-java) the endpoint for the init method is "/maestrano/auth/saml/init/{marketplace}" and the marketplace will be then retrieved as a parameter.
@RequestMapping(value = "/maestrano/auth/saml/init/{marketplace}", method = RequestMethod.GET)
public ModelAndView init(@PathVariable("marketplace") String marketplace, @RequestParam Map<String, String> allRequestParams) {
//..
If your application is installed in the marketplaces vagalam and doritor, the url called will be /maestrano/auth/saml/init/vagalam if the call is coming from the vagalam marketplace and /maestrano/auth/saml/init/doritor if it is coming from the doritor marketplace.
Init Method
During a SSO process, Maestrano will first do a GET call to the SSO Init Path url with the appropriate marketplace. Your application should then use the SDK to retrieve and redirect to the SSo url.
class SSOController{
// Route GET "/maestrano/auth/saml/init/{marketplace}" to this method
function init(Hash requestParameters){
// Retrieve the configuration for the given marketplace
marketplace = requestParameters["marketplace"]
config = MaestranoConfig.get(marketplace)
authReq = new Authrequest(config, u)
ssoUrl = authReq.getRedirectUrl();
redirectTo(ssoUrl)
}
}
Examples in
Consume Method
Maestrano will check that everything is in order and then do a POST request to the SSO Consume Path url containing all the required information to identify the user and his organization connecting to your application.
class SSOController{
// Route POST "/maestrano/auth/saml/consume/{marketplace}" to this method
function consume(Hash requestParameters){
// Retrieve the configuration for the given marketplace
marketplace = requestParameters["marketplace"]
config = MaestranoConfig.get(marketplace)
samlResp = config.getSso().buildResponse(requestParameters["SAMLResponse"])
if(samlResp.isValid()){
// Build MaestranoUser and MaestranoGroup (coming from the SDK)
mnoUser = new MaestranoUser(samlResp);
mnoGroup = new MaestranoGroup(samlResp);
// Build/Map local entities
var localGroup = MyGroup.FindOrCreateForMaestrano(marketplace, mnoGroup);
var localUser = MyUser.FindOrCreateForMaestrano(marketplace, mnoUser);
// Add localUser to the localGroup if not already part of it
if (!localGroup.HasMember(localUser)){
localGroup.AddMember(localUser);
}
var session = getCurrentHttpSession();
session["marketplace"] = marketplace;
// Set Maestrano session - used for Single Logout
config.getSso().setSession(session, mnoUser);
return redirect("/");
}else{
return content("Invalid SAML Response");
}
}
}
Examples in
4 What do I have to pay attention to?
The uid specified in the SSO request is an User identifier. It must be stored against the User record on your side so even if a user changes its email, you can still uniquely identify its account. The uid is unique per marketplace - not cross marketplaces.
The group_uid specified in the SSO request is an identifier of an account in your application. It will help you to assign the Users against the Company/Organization they belong to as well as the identifier used for the Connec! data-sharing. You need to store this value against the user company inside your application. The group_uid is unique per marketplace - not cross marketplaces.
On a platform, a User can be part of multiple Companies (one uid for more for more than one group_uid) and a Company can have multiple Users (several uid for the same group_uid). We ask every application on to respect this norm, and to help you implement that, we propose you virtual ids on our SDKs that are unique for a user and a company (not cross marketplaces).
Unicity with multi-marketplaces
If a user opens an account on two different tenants, two different accounts must be created to avoid mixing data between different organisations in different marketplaces.
Do not send emails to virtual email addresses
The virtual email addresses should only be used to create a unique user id, not to send emails to users; for that, you can always reach the user's real email.
5 SSO Consume process
