SSO Process

1 - SSO, what for?

SSO allows for users to launch your application directly from the platform's dashboard without having to type in credentials (enhancing the user experience)

2 - A user launches your application for the first time from their dashboard, what next?

When accessing your application for the first time, a new account must be created based on the incoming user details (first name, last name, email, company name etc...). You also may have different subscription plans to be offered to the user.

To encourage uptake, Maestrano strongly recommend the user account is setup under a free trial under an applicable subscription tier(if supported). Once the free trial has lapsed, the user can be charged via the Billing API.

As part of the SSO process, the user details are passed on (first name, last name, email etc). You can decide to use this 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?

1. The Single Sign On process is initiated from the platform when a user clicks on your application from their dashboard
2. The user is redirected to the configured SSO initialization endpoint which then redirects back to the marketplace IDM endpoint
3. 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.

Note: the SSO Init Path and Consume Path are configured in our dedicated Maestrano Developer Platform per environment (as pictured below).

Figure 1 -The Maestrano Developer Platform → Technical Section

These path should contains a variable that indicate the correct 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

• Java
• Dotnet
• Rails
• Php

Consume Method

Maestrano will first 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

• Java
• Dotnet
• Rails
• Php

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 their email, you can still uniquely identify their 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 use virtual ids on our SDKs that are unique for a user and a company (not cross marketplaces).

5 - SSO Consume process