Skip to main content
Matrix42 Self-Service Help Center

Step-by-Step Configuration of AD FS for SASM using MyWorkspace with SAML2

Introduction

This Article describes how to prepare and configure your AD FS for SAML2 Login to Software Asset & Service Management (SASM). This article requires that you have a Matrix42 MyWorkspace (MWS) Subscription, a fully functional AD FS Infrastructure and a running SASM. 

Please Note: Login via SAML2 is only possible with MWS Accounts.

In this guide we are assuming you are going to use the E-Mail address as NameID Policy.

IN A NUTSHELL

  • AD FS
    • Confire AD FS Relaying Party Trust (this article)
    • Configure Claims Issurance Policy (this article)
  • Software Asset & Service Management
    • Configure SAML2 Authentication (this article)
    • Configure MWS Connector (external article)
  • MyWorkspace

Prerequisites

  • You will need administration Accounts for the following components
    • AD FS Admin
    • MWS Admin
    • SASM Admin
  • The following configurations must be in place
    • STS Token must be activated in SASM (For Matrix42 Cloud Environments this is activated by default)
  • (optional)
    • already configured MWS Connector in SASM
    • already configured Cloud Connector (AD) in MWS

PREPARE AD FS RELAYING PARTY TRUST FOR SASM

In this part of the guide we're preparing the AD FS relaying party trust so that the AD Users from your AD FS are able to connect to SASM. 

  • Open your AD FS console
  • Navigate to "Relaying Party Trusts" and create a new object
  • Choose "Claims aware" in the First page of the Wizard

    1_Claims.JPG
  • At "Select Data Source" use the last option "Enter data about the relaying party manually"

    2_datasource.JPG
  • At the "Specify Display Name" of the Wizard fill in something that identifies the relaying trust as a SASM related configuration.

    3_displayname.JPG
  • Do nothing at the "Configure Certificate" area (encrypted communication is not supported at the moment)
  • At the "Configure URL" Page of the Wizard check the "Enable Support for the SAML 2.0 Web SSO protocol" option and fill in your SASM URL followed by: 
    /m42services/authorize/login
    In my case the URL looks like: https://cha.m42cloud.com/m42services/authorize/login

    4_configureurl.JPG
  • At the "Configure Identifiers" Wizard Page fill in your Top Level Domain as the trust identifier and click "Add"

    5_identifier.JPG
  • For the "Access Policy" we are going to use "Permit everyone". Depending on your companies policies and configuration this may vary.
  • Review your settings in "Ready to add trust" and finish the Wizard.

ADD AD FS CLAIM ISSURANCE POLICIES 

Since there is a need to transform some data from AD / AD FS in order to ensure a login we will need to create two claim issurance policies.

  • Highlight your newly created SASM relaying party trust and click "Edit Claim Issurance Policy" in the right pane. 
  • In the grid that opens click "Add Rule
  • At the "Choose Rule Type" page select "Send LDAP Attribute as Claims" from the "Claim rule template" dropdown. 

    6_claimrule1.JPG
  • At the "Configure Claim Rule" page of the Wizard fill in the Claim rule name. We suggest "E-Mail" here. 
  • From the" Attribute Store" dropdown choose "Active Directory"
  • Create a mapping and fill in as "LDAP Attribute": E-Mail-Addresses
  • Fill "Outgoing Claim Type": E-Mail-Address
  • Click "Finish"

    7.2_claimrul2.JPG
  • Now we need another rule, click "Add Rule" again.
  • From the "Claim rule template" dropdown choose "Transform an Incoming Claim" this time

    7_claimrule2.JPG
  • Set the Claim rule name to "E-Mail to NameID"
  • For the “Incoming claim type” choose “E-Mail Address
  • For the “Outgoing claim type” choose “Name ID
  • For the “Outgoing name ID format” choose “Email
  • Activate the “Pass through all claim values” radio button. (default)

    8_claimrule3.JPG
  • Finish the Wizard
  • You should have two Claim Issurance policies in place now:

    9_rules.JPG
  • The AD FS Configuration is now done. 

CONFIGURE SASM FOR SAML2 AUTHENTICATION

In this step, we are preparing the SASM instance to let users authenticate with SAML2. You will need the following things as prerequisite:

  • AD FS Login Endpoint
  • AD FS Logout Endpoint
  • Identity Provider Certificate String (Token signing)

 

  • Open your SASM instance
    • Navigate to Administration > Settings > Edit > Secure Token Service
  • Fill the following fields:
    • SAML2 Login Button Title
      • Fill in anything you like but give your users a hint that this is the Button for SAML 2 Login)
    • SAML2 Identity Provider ID
      • This is the Domain of your AD FS Instance
    • SAML2 Service Provider Issuer Name
      • The Domain of your SASM Installation (as configured in the AD FS relaying trust)
    • Single Sign-On URI Endpoint
      • Your AD FS Logout Endpoint (This can also be found in your AD FS Configuration under Service > Endpoints. By default this is <FQDN of your AD FS>/adfs/ls/?wa=wsignout1.0)
    • Fill in your “Identity Provider Certificate” string
      • You could extract this from your Metadata.xml in AD FS (This can be usually found in <FQDN of your AD FS>/FederationMetadata/2007-06/FederationMetadata.xml). We are use the “signing” certificate here. This can also be found in your AD FS configuration (Service > Certificates > Token signing).
    • Set the SAML2 Name ID Policy to "E-Mailaddress"
    • When you're done it should look something like this: 

      10_adfs_svs_cfg.JPG
    • When you activate "Single Sign On" users will be automatically logged in when already authenticated with AD FS. (recommended).
    • The SAML2 Configuration is now done and SASM is now ready to accept logins via SAML2 from your AD FS Instance. 
    • Before Users are finally able to authenticate you need to import them to from AD (FS) to MWS first. And then configure SASM to import these Users from MWS to your SASM Instance. 

CONFIGURE MWS CLOUD CONNECTOR AND SASM MWS CONNECTOR

As mentioned above you'll now need the users from your AD (FS) Instance imported to SASM so that they can finally login. Since there are extra articles for those configurations i am only going to refer to them here.

Here is the flow in a Nutshell: 

  • Download and Configure MWS Cloud Connector for AD (For User Import from AD to MyWorkspace) (Article - Video)
    • Wait until all users are imported
  • Create an Authentication Token for SASM via M42 Accounts (Article - See: Prerequisites for Importing Accounts Step 1)
  • Configure SASM MWS Connector (for User import from MWS to SASM) (Article)
    • Since you only want to import the Users you can skip the "Sign On" (SSO) Part.
  • As soon as Users from MWS are imported to SASM, they are able to login via SAML2 Authentication. 
    • Please note: Users logged in this way will have no role assigned and will only be able to see the SASM Portal. 
      • Roles have to be assigned manually after the import has been taken place.  
  • Final Note: If you happen to "lock out" yourself from SASM (if your AD FS is down for example, network issues etc.), you could always FORCE the login by using the following parameter in your SASM URL: /wm?ForceLoginPage=true (Example: https://cha.m42cloud.com/wm?ForceLoginPage). This bypasses the default (SAML2 SSO in this case) authentication and enables you to login with an Internal Domain user for example.