MasterLibrary SAML Configuration and Setup for Single Sign On

MasterLibrary Software gives subscribers the option to integrate their current Identity Provider with our software so users can continue to login to their existing system, and then click the MasterLibrary product icon to authenticate. SAML is the MasterLibrary recommended user authentication method.

There are (3) simple one-time procedures that must be performed to integrate your district’s current Identity Provider with MasterLibrary Software:

1. Create a SAML application within your Identity Provider.
2. Configure your Identity Provider within MasterLibrary Software.
3. Set default Roles for Users who login via this new SAML integration.

Already have SSO implemented and have questions about your existing configuration?
Click this link for Frequently Asked Questions regarding SAML.

Step 1: Create a SAML application within your Identity Provider.

MasterLibrary currently supports the following Identity Providers:

1. Google
2. Microsoft Azure
3. Okta

Note: If your district uses another Provider and would like MasterLibrary to integrate with them, please contact us and we will be happy to discuss.

Google SAML Setup

• Login to your Google Admin Console at https://admin.google.com/
• Browse to Apps → Web and Mobile Apps
• Click Add App → Add Custom SAML App
• Fill out the App Name to correspond to the MasterLibrary product and upload the image provided by MasterLibrary for the icon
• 
• Copy the SSO URL and the Certificate as they will be used in Step 2 below
• Service Provider Details
  • The ACS URL and Entity ID will both be the same
    • https://XXXXX.mlschedules.com/MLSAMLConnect.aspx
      • Replace “XXXXX” with your custom MasterLibrary subdomain
  • For Name ID format select “Persistent” 
  • For Name ID select “Basic Information > Primary email”
• Attribute Mapping
  • You will map 3 attributes here and they need to match exactly as entered here
    • Basic Information - Primary Email
      • Email
    • Basic Information - First name
      • FirstName
    • Basic Information - Last name
      • LastName
  • Group membership
    • This is where you will select the Groups you want to pass through to automatically assign Role(s) to the Users within MasterLibrary.  This is optional but a nice way to give Users some default roles and capabilities, especially if you segment within Groups in Google already.

Microsoft Azure SAML Setup

• Login to your Azure Portal at https://portal.azure.com/
• Browse to Azure Active Directory
• Click Enterprise Applications → New Application → Create your own application
• Give it a name to match the MasterLibrary product and select “Integrate any other application you don't find in the gallery (Non-gallery)”
• Click “Single sign-on” and then select “SAML”
• Basic SAML Configuration
  • Identifier (Entity ID)
    • Enter a unique name that corresponds to the MasterLibrary product
  • Reply URL (Assertion Consumer Service URL)
    • https://XXXXX.mlschedules.com/MLSAMLConnect.aspx
      • Replace “XXXXX” with your custom MasterLibrary subdomain
• Attributes & Claims
  • You will map 3 new additional attributes via “Add Claim” here, and they need to match exactly as entered here  
    
    • FirstName
      • user.givenname
    • LastName
      • user.surname
    • Email
      • user.mail
  • Add a group claim (optional)
    • This is where you will select the Groups you want to pass through to automatically assign Role(s) to the Users within MasterLibrary.  This is optional but a nice way to give Users some default roles and capabilities, especially if you segment within Groups in Azure already.
    • You can select “All Groups” or select specific ones if you’d prefer
    • The source attribute is “Group ID”
    • Under Advanced Options select “Customize the name of the group claim” with a Name of “Group”
    • 
      
• SAML Certificates
  • Click edit to pop the sidebar and then click the dots next to the Active certificate and select "Base64 certificate download”
    • This will download a file you will need to open for Step 2 below within MasterLibrary
• Click “Assign users and groups” to grant access to this application to a subset of your Users

Okta SAML Setup

• Login to your Okta Dashboard
• Go to Applications → Create App Integration
• For Sign-in method select “SAML 2.0”
• General Settings
  • Enter a unique App Name to correspond to the MasterLibrary application
• SAML Settings
  • Single sign-on URL
    • https://XXXXX.mlschedules.com/MLSAMLConnect.aspx
      • Replace “XXXXX” with your custom MasterLibrary subdomain
  • Check the box for “Use this for Recipient URL and Destination URL”
  • Application username
    • Select “Okta username”
  • Attribute Statements (optional)
    • FirstName
      • user.firstName
    • LastName
      • user.lastName
    • Email
      • user.email
  • Group Attribute Statements (optional)
    • This is where you will select the Groups you want to pass through to automatically assign Role(s) to the Users within MasterLibrary.  This is optional but a nice way to give Users some default roles and capabilities, especially if you segment within Groups in Okta already.
• Select “I'm an Okta customer adding an internal app”
• SAML Signing Certificates
  • Next to the active certificate select “Actions → Download certificate”
  • This is the text you will copy/paste into MasterLibrary in step 2

Step 2: Configure your Identity Provider within MasterLibrary Software.

Once you log in to your MasterLibrary product you will navigate to Admin → Single Sign On → SAML Configuration.  From there you will configure your provider by:

1. Update the Issuer to contain the URL for your Provider.
2. For Google: The Login Link field can be left blank.
   
   For Azure: Copy the “User access URL” under the Properties menu and enter it in the Login Link field.
   
   
   
   For Okta: Copy the “App Embed Link” and enter it in the Login Link field.
   
3. Copy/paste the Certificate you generated in your Provider configuration in Step 1.
4. If using ML Schedules, you will also set the Classification to create new Groups for these Users in.
   
   

Step 3: Set default Roles for Users who login via SAML.

Once you log in to your MasterLibrary product you will navigate to Admin → Single Sign On → SAML Group Settings.  From there you will configure the SAML Groups you indicated in Step 1 and what default set of Roles you want to give to Users within that Group.

*Passing "Group" is required, but using Groups to actually give default Roles is not.*

Note: You can create as many SAML Groups as you’d like, and each time a User logs in they will get whatever Roles you indicate on all of the Groups they are a part of.  You can also manage additional Roles within MasterLibrary as usual, but you can not remove these default ones so make sure they apply to all users within the group.

For Google: Group Name field will be the Group Names established in Step 1

For Azure: Group Name field will be the Object ID for each group established in Step 1

For Okta: Group Name field will be the Group Names established in Step 1