Matrix42 Workspace Management 8.1.2 supports identity federation with SAML 2.0 (Security Assertion Markup Language 2.0). This feature enables federated single sign-on (SSO) – session and user authentication service that permits a user to use one set of login credentials to access multiple applications like Matrix42 Workspace Management, Matrix42 MyWorkspace, Matrix42 MarketPlace.
To use universal STS/SAML2 authentication you need to configure:
Configuring MyWorkspace application for SSO
- Go to https://myworkspace.matrix42.com/ and sign in with your Matrix42 administrator account.
- Go to “Applications” and add new “Custom Saml2 Service Provider” application:
- Enter Application name;
- Enter Service Provider URL;
- Enter Service Provider Issuer name;
- Enter Saml2 client name;
- Set the NameId format to the nameid-format:emailAddress (Saml 2.0)
- Check “If set to true, then the Saml2 response will be signed.”
- Check “If set to true, then the Saml2 assertion section will be signed.”
- Check the “If set to true, then the Saml2 response will be encoded and sent in base 64 format” checkbox.
- Set the Saml2 response validation url to the https://[EnterYourServerDomainName]/m42services/api/sts/login
- Set the Logout Url to the:
- Choose the algorithm to be used to sign your Saml2 response. Select SHA256 and save the application.
- Now you should be able to download The Integration Guide.
Identity Provider enabled login
You can launch an application directly from MyWorkspace. You have to uncheck "Identity provider initiated single sign-on" and provide as the service provider URL the "SingleSignOnService location" from the Integration Guide.
In the background, the system will initiate an IdP initiated SAML2 flow and will send a SAML2 reply to the SAML2 response validation URL.
Configuring login page to support different login methods
In the Administrative area of the Matrix42 Workspace Management you are allowed to:
- Enable single sign-on
- Enable browser credentials
- Enable SAML2
Configuring SAML2 Authentication
To enable SAML2 authentication you should specify:
On the SAML2 Identity provider side:
- Set the Saml2 response validation url to https://[EnterYourServerDomainName]/m42services/api/sts/login
- Set the Logout Url to: https:// [EnterYourServerDomainName]/m42services/api/sts/logout
- Choose the algorithm to be used to sign your Saml2 response. SHA256 should be specified.
On the Service Store side:
- SAML2 Login Button Title: it will be visible on the “Sign In” page.
- SAML2 Identity Provider ID: use the same as it was specified in the SAML2 identity provider side application for the “Service Provider URL” field (for MyWorkspace this is normally https://accounts.matrix42.com).
- SingleSignOn/Out URI Endpoints: use the ones that are provided by the identity provider (for MyWorkspace you can find them under integration guide).
- Service Provider Issuer Name: use the same as it was specified in the SAML2 identity provider side application for the “Service Provider Issuer name (Unique Resource ID)” field.
- Identity provider certificate: use the x509 Certificate Key provided by your SAML2 provider (in case of myworkspace you can use one from the Integration guide).
- SAML2 Name Id Policy: your SAML2 provider will provide you with a Name Id after login, the SAML2 specification allows different kinds of the Name ID. Some providers expect that an application asks for a specific kind in the initial request; here you can set this policy for the Name Id field.
- SAML2 Name Id Allow Create: In the initial SAML2 request an "AllowCreate" attribute for the Name Id can be set. Different providers expect different settings or not providing this attribute at all.
- Disable logout from Saml2 provider: If the user logs out of the application, you can specify whether you want to keep your session with your SAML2 provider or also send a logout request to your SAML2 provider.
- Sign Logout to Saml2 provider: instructs to sign the Logout request with the certificate, it is required by some Identity Providers (like Okta). If the signing of the Logout request is activated, the public certificate needs to be uploaded to the Identity Provider for further description of received messages. Use the "DOWNLOAD (.cer file)" button to obtain the public certificate
- The System uses the Web Server private SSL certificate.
In the image below, you can see an example of how to configure SAML2 on the service store side in case Myworkspace.matrix42.com is used as the SAML2 identity provider:
The Single Sign On Uri Endpoint can be copied from the Metadata .xml document. To download it open the MyWorkspace Integration Guide for the created application and follow the link from Step 2.
Bypass Automatic Login
It may happen that for some reason your SAML2 authentication no longer works. In case of Single sign-on enabled, you now have the issue that you are no longer able to enter the application to change your configuration, maybe to update the certificate. In this case you can force the system to show you the login page to make it possible to login with a non SAML2 account. You have to add the predefined parameter "ForceLoginPage" to your url, like this: https://myhost.mydomain.com/wm?ForceLoginPage
The example describes how the Okta Identity Provider can be configured for authentication.
Configure Matrix42 App on Okta side
- Go to Okta Admin console and create a new Application for Matrix42 website;
- Choose "Web" as platform and "SAML 2.0" as sign-on method;
- Enter an app name in General Settings;
- Configure SAML settings.
Okta integration with Matrix42 requires the "Enable Single Logout" activation, and defining the Signature Certificate. To obtain the Signature Certificate open the Matrix42 UUX console Administration Settings / page Secure Token Service, and click button "DOWNLOAD (.cer file)"
Configuring Okta in Matrix42
For Okta integration the checkbox "Sign Logout to Saml2 provider" has to be set.
The example describes how the Google Identity Provider can be configured for authentication.
Configure Matrix42 App on Google side
Go to Google Admin console and create a new application for Matrix42 website:
- In the Admin interface, select Apps → SAML Apps → Add new → Setup my own custom App;
- You will need the following data from this step for Google IdP configuration in Matrix42:
- SSO URL: use this value for Single Sign-on URI Enpoint field in Matrix42 Secure Token Service configuration;
- Entity ID: use this value for SAML2 Identity Provider ID field;
- Certificate: use the key value from the downloaded file for Identity Provider Certificate field;
- Provide basic information for your Custom App: Application Name, optional Description, and upload logo;
- Specify the Service Provider Details:
- ACS URL value depends on your Matrix42 version:
- 10.0.0 or greater:
- 9.1.3 or lower:
- 10.0.0 or greater:
- Entity ID:
You can find your
discoveryHostName value in the SPS.config file.
Save the App settings and proceed to Matrix42 configuration.
Configuring Google IdP in Matrix42
For Google integration, open Administration application → Settings → Secure Token Service.
Set the SAML2 enabled checkbox and fill out the fields with necessary credentials from the second step of the Google IdP configuration:
|Matrix42 settings & corresponding fields||Google IdP SAML Apps settings|
|Single Sign-on URI Enpoint||SSO URL|
|SAML2 Identity Provider ID||Entity ID|
|Identity Provider Certificate||Certificate file|