Our technical documentation is moving
PortalGuard has support for SAML 2 integrations. Integrating PortalGuard with IE's applications requires configuration in PortalGuard and also in the specific IE application that is being used. If more than one IE application is being used, then the integration needs to be completed for each application.
Note: Local adaption of these instructions maybe needed.
PortalGuard will be acting as the SAML identity provider (IdP). To configure a PortalGuard Relying Party Trust, some information from the IE application is needed.Â
If a client configuration is being used, browse to the Panorama section, and click Manage on the appropriate client.
If a client configuration is not being used, click the Settings link
Then click the Single Sign On link.
On the Single Sign On page, scroll down to the SAML 2.0 Settings section.
Right click on the Download SAML Metadata button and click Save Link As...
Save the file to disk.
The SAML 2.0 Settings section and Download SP Metadata button
To complete the IdP configuration in PortalGuard, we need to create a Relying Party with the following settings:
On the General tab:
Name: Enter a desired name. This is a free form field, but it is recommended to enter the Innovative Educator's application name.
Identifiers: Copy and paste the value of the entityId from the Innovative Educators application's metadata file.
Binding: Set to POST.
Assertion Consumer URL: From the Innovative Educators application's metadata file, find the element named AssertionConsumerService with a Binding attribute value of urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST, copy the value of the Location attribute and pasted it into PortalGuard.
State: Ensure that it is checked.
On the Response tab:
Default RelayState: (blank)
SAML Version: 2.0
Digest Algorithm: SHA-1
Signing Algorithm: SHA-1
Sign SAML Response?: unchecked
Sign SAML Assertion?: checked
Override Token Timeout?: unchecked
NotBefore Clock Skew: 0
Override IdP Issuer: (blank)
Override Cannonicalization: (blank)
PortalGuard now knows about the Innovative Educator's application.Â
We need to instruct PortalGuard to send some information about the user to the SP:
In the Relying Party window, select the Identity Claims tab.
Select the appropriate Attribute Store.
For each of the attributes, click Create and then populate the settings:
First Name (required):
Name: firstname
Send As NameID?: unchecked
Schema Type: firstname
Value Type: String Field
Convert Case: (No Change)
Direct Field->Field Name: givenName
Direct Field->Value Index: 0
Last Name (required):
Name: firstname
Send As NameID?: unchecked
Schema Type: lastname
Value Type: String Field
Convert Case: (No Change)
Direct Field->Field Name: sn
Direct Field->Value Index: 0
Email Address (required):
Name: email
Send As NameID?: unchecked
Schema Type: email
Value Type: String Field
Convert Case: (No Change)
Direct Field->Field Name: email
Direct Field->Value Index: 0
NameId/Username (required):
Name: NameID
Send As NameID?: checked
Schema Type: (blank)
Value Type: String Field
Convert Case: (No Change)
Direct Field->Field Name: (uid, sAMAaccountName or other identifying attribute)
Direct Field->Value Index: 0
licenseIds (if provided by IE):
Name: firstname
Send As NameID?: unchecked
Schema Type: licenseIds
Value Type: Formatted String
Convert Case: (No Change)
Formatted->Composite Value Format: (enter the licenseId provided by Innovative Educators)
If passing additional attributes (Ref1, Ref2, Ref3), repeat the steps for each using Email as an example.
Click Save.
PortalGuard is now ready to authenticate users to the IE application.
The Name Identifier is the unique ID that will identify SAML users coming from the IdP (identity provider).
Requirements
Must be unique across the instance: This value of the NameId must be unique across all learners of every client in an instance. This means that if you share an instance with other clients (almost everyone), then your ID must not clash with other client's learners. Some good options include:
Email Addresses
Appending the school domain name to a name or ID
Or utilizing an ID random enough to sufficiently collision resistant
Recommendations
Use an ID that doesn't change: Since this value used to sync learner to their accounts or create a new account if one doesn't exist for a learner, it's recommended that this value be from a source that doesn't change. If the value does change, then the learner will receive a fresh account upon authenticating and will lose all previous progress.
Email Address as NameId will suffice : Sending an email as the NameId can cause the problem mentioned above when a learner's email changes due to a name change. That said, email addresses are used by many clients without much headache. Though it isn't the "perfect" option, we considered it "good enough".
Unique IDs are a better option: If available, an ID with sufficient randomness to be collision resistant, or appending a domain or school name to less random ID, has the benefits of being both unique and unchanging.
The populated NameID attribute definition
The populated LicenseIds attribute
The IdP-Initiated tab
The Response tab
Users can login by accessing the URL https://www.go2knowledge.org/access/saml/login/<client-slug> or https://<school domain>/access/saml/login.