Client setup for Single Sign-On (Generic) endpoint in their IdP using the SAML 2.0 protocol for a Frontline application. Steps and roles to establish for the Asset Management application.
The API Secret displayed under API and SSO information is to connect to the Frontline Asset Management Rest API. The data accessed by the API are tags distributed to Staff or Students and the statuses associated with them.
- Navigation:
- Admin View
- District Settings
- API and SSO Information
Table of Contents
Configuration Checklist
Frontline Configuration
The following items have been setup/created by Frontline in order to kick off the SSO setup:
| Num | Item | Value | |
|---|---|---|---|
| 1 | Relying Party Identifier (Assertion Consumer) URL for Desktop | https:///TIPIDCore/ | |
| 2 | Relying Party Identifier (Assertion Consumer) URL for Mobile | https:///TIPWebITMobile-Login/ | |
| 3 | SAML 2.0 Endpoint for Desktop | https://HayesURL/TIPIDCore/SSO/ADFSLogOn.aspx | |
| 4 | SAML 2.0 Endpoint for Mobile | https:///TIPWebITMobile-Logon/SAML/SAMLConsumer | |
| 5 | Your school's primary email domain | DistrictDomainName |
District Configuration
The following items must be completed and sent to Frontline for the SSO setup to be successful:
| Num | Item | Instructions | |
|---|---|---|---|
| 1 | Create AD user groups | Create AD User Groups for Asset Management and Mobile SSO | |
| 2 | Create a Frontline user in your ADFS | Create an ADFS account for Frontline support users | |
| 3 | Send the Frontline user credentials to ihdmsuppor@frontlineed.com | ||
| 4 | Add relying party identifiers (Assertion Consumers) for both desktop and mobile | Add Relying Party Trusts | |
| 5 | Add SAML 2.0 endpoints for both desktop and mobile | ||
| 6 | Ensure the correct claim values are setup in ADFS | Claim Values Expected | |
| 7 | Setup a claims rule for the relying party | Claims Rules for the Relying Party | |
| 8 | Generate the IdP Metadata file or URL | Generate and Send the IdP Details | |
| 9 | Generate the entity ID used by the IdP | ||
| 10 | Generate the certificate used to sign SAML 2.0 | ||
| 11 | Send the IdP Metadata file or URL to ihdmsuppor@frontlineed.com. |
Overview of What Asset Management Needs
To integrate ADFS SSO with Frontline Asset Management, you must have a valid Active Directory Federation Services (ADFS) Single Sign-On (SSO) solution created by Microsoft. If you don't have an ADFS setup, you can read about it here: Active Directory Federation Services.
These are the steps that you will need to follow in order to allow Frontline to configure Asset Management to SSO into your ADFS instance. They are described in detail in the following sections:
- Create AD User Groups for Asset Management and Mobile SSO
- Create an ADFS account for Frontline support users
- Add a Relying Party Trust for each product Asset Management and Mobile
- Generate the IdP Metadata File or URL, entity ID and signing certificate using SAML 2.0
- Send the ADFS account and credentials, and the IdP details to the Frontline team
Create AD User Groups for Asset Management and Mobile SSO
You must create the following groups in AD, and all Asset Management users must be assigned to one of these groups:
| Required Group Name | Description |
|---|---|
| TIPWEBIT_ADMINVIEW_ADMIN | An administrative level user with admin level permissions. |
| TIPWEBIT_ ADMINVIEW_USER | An administrative user. They have similar rights as the admin user, except a few application maintenance features. |
| TIPWEBIT_SITEVIEW_ADMIN | A site level administrator who only has access to their site data. |
| TIPWEBIT_SITEVIEW_USER | A site user who can only work with their site data. |
| TIPWEBIT_LOOKUPVIEW_USER | A view-only used to lookup tags existing in TIPWeb IT. |
Create an ADFS account for Frontline support users
Create the following user in your Active Directory for Frontline Support Staff with a password that does not expire:
- Username: tipweb_it
- Add to group: TIPWEBIT_ADMINVIEW_ADMIN
- Add an email address such as tipweb_it@DistrictDomainName
Add Relying Party Trusts
Asset Management
Create a new, separate relying party trust in your ADFS. Do not combine it with any other, existing, or new relying party trust.
Relying Party Identifiers
https://HayesURL/TIPIDCore/
Endpoints
This must be a WS-Federation Passive endpoint and must have a POST binding.
https://HayesURL/TIPIDCore/SSO/ADFSLogOn.aspx
TipWeb-IT Mobile
Create a new, separate relying party trust in your ADFS. Do not combine it with any other, existing, or new relying party trust.
Relying Party Identifiers
https://HayesURL/TIPWebITMobile-Login/
Endpoints
This must be a WS-Federation Passive endpoint and must have a POST binding.
https://HayesURL/TIPWebITMobile-Logon/Account/LoginADFS
When you have setup the SSO endpoint for Asset Management in your IdP, fill out the required fields in Configuration Document, and send it to ihdmsupport@frontlineed.com.
Claim Values Expected
- Claim Type Name = Username (NameID = Username)
- Claim Type Email = email address
- Claim Type Given Name = First Name
- Claim Type Sur Name = Last Name
- Claim Type Phone = Phone number
- Claim Type Role = USER GROUPS FOR TIPWEB-IT
<md:RequestedAttribute isRequired="true" Name="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="Given Name"/>
<md:RequestedAttribute isRequired="true" Name="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="Surname"/>
<md:RequestedAttribute isRequired="true" Name="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="name"/> => UserName
<md:RequestedAttribute isRequired="true" Name="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="email"/>
<md:RequestedAttribute isRequired="false" Name="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="Phone"/>
<md:RequestedAttribute isRequired="true" Name="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="Role"/>
Claim Rule for the Relying Party
A claim rule must exist for each product: Asset Management and Mobile.
Sample SAML Request and Response
Request
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
ID="_591df756-862f-40ff-8b87-2624fbf38c86">
Version="2.0"
IssueInstant="2021-09-10T15:37:21Z"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
AssertionConsumerServiceURL="https://HayesURL/TIPIDCore/SSO/SAMLConsumer.aspx"
Destination="https://__your_SSO_Login_URL__"><saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://HayesURL/TIPIDCore/</saml:Issuer>
</samlp:AuthnRequest>
Response
The SSO IdP must send back a SAML response to Asset Management that is similar to the following:
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_93883a0f-fa68-42d7-8444-c61473ea706c" Version="2.0" IssueInstant="2021-09-08T17:49:02.278Z" Destination="https://HayesURL/TIPIDCore/SSO/SAMLConsumer.aspx" InResponseTo="_f9948222-3e11-4592-a0f6-7f15c2812131"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://sts.windows.net/90e0c2f4-c0eb-4f28-b0f5-8d2c578af4c8/</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></samlp:Status><Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_6cf241dc-38c0-4881-9b8b-cd751eda6701" IssueInstant="2021-09-08T17:49:02.278Z" Version="2.0"><Issuer>https://sts.windows.net/90e0c2f4-c0eb-4f28-b0f5-8d2c578af4c8/</Issuer><Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /><SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" /><Reference URI="#_6cf241dc-38c0-4881-9b8b-cd751eda6701"><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" /><Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /></Transforms><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" /><DigestValue>...</DigestValue></Reference></SignedInfo><SignatureValue>...</SignatureValue><KeyInfo><X509Data><X509Certificate>...</X509Certificate></X509Data></KeyInfo></Signature><Subject><NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">tipweb_it@DistrictDomainName</NameID><SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><SubjectConfirmationData InResponseTo="_f9948222-3e11-4592-a0f6-7f15c2812131" NotOnOrAfter="2021-09-08T18:49:01.997Z" Recipient="https://HayesURL/TIPIDCore/SSO/SAMLConsumer.aspx"/></SubjectConfirmation></Subject><Conditions NotBefore="2021-09-08T17:44:01.997Z" NotOnOrAfter="2021-09-08T18:49:01.997Z"><AudienceRestriction><Audience>https://HayesURL/TIPIDCore/</Audience></AudienceRestriction></Conditions><AttributeStatement><Attribute Name="http://schemas.microsoft.com/identity/claims/displayname"><AttributeValue>Hayes Support</AttributeValue></Attribute><Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"><AttributeValue>Hayes</AttributeValue></Attribute><Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"><AttributeValue>Support</AttributeValue></Attribute><Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"><AttributeValue>tipweb_it@DistrictDomainName</AttributeValue></Attribute><Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"><AttributeValue>tipweb_it@DistrictDomainName</AttributeValue></Attribute><Attribute Name="role"><AttributeValue>TIPWEBIT_ADMINVIEW_ADMIN</AttributeValue></Attribute></AttributeStatement><AuthnStatement AuthnInstant="2021-09-08T17:39:00.607Z" SessionIndex="_6cf241dc-38c0-4881-9b8b-cd751eda6701"><AuthnContext><AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef></AuthnContext></AuthnStatement></Assertion></samlp:Response>
Generate and Send the IdP Details
Metadata File or URL
The federation metadata document is an XML file that is available for download at the following ADFS endpoint: https://DistrictDomainName/federationmetadata/2007-06/federationmetadata.xml. It contains information about your federation service that is used to create trusts, identify token-signing certificates, and many other things. It needs to be publicly available so that other parties — such as Asset Management — can access and consume it.
Asset Management relies on the XML document or a URL to the document to access your ADFS instance.
IdP URL for Redirection
The following is a sample redirection URL for your ADFS SAML 2.0 setup:
https://[your-adfs-domain.com]/adfs/ls
Entity ID Used by the IdP
The following is an Entity ID URL for your ADFS SAML 2.0 setup:
https://[your-adfs-domain.com]/adfs/services/trust
Token Signing Certificate or Thumbprint
Asset Management needs either the thumbprint or the X509 certificate used to sign the ADFS token.
Go to (or get) the federation metadata XML from:
https://DistrictDomainName/federationmetadata/2007-06/federationmetadata.xml
Open the XML in a text editor, and locate the node:
RoleDescriptor xsi:type="fed:SecurityTokenServiceType" -> KeyDescriptor use="signing" ->X509Data ->X509Certificate
Copy and send/use the large string between the <X509Certificate>...</X509Certificate> nodes.
In ADFS management sidebar, go to AD FS > Service > Certificates and double click on the certificate under Token-signing. You may alternatively right click the field, then click View Certificate.
In the "Details" tab, scroll to the bottom, and copy and use the "Thumbprint".
FAQs
Should I name the URLs, file names, projects, and Google settings exactly as documented here?
Yes. Please do not change them as Asset Management depends on the specific names that are requested here.