PacketFabric uses SAML to provide single sign-on (SSO) functionality.
Most of the SAML configuration is done from the identity provider (IdP) side. As each IdP is different, you should refer to their documentation for configuration instructions.
Add an SAML identity provider (IdP)
-
Log in to the PacketFabric portal as an Admin user. Click your company name in the upper right and select SAML & SSO:
-
Under Add identity provider complete the following fields:
- Header row
- Row 1
- Title
- Enter a name for this identity provider (IdP). This is for your reference and does not need to match the actual name of the IdP.
- Row 2
-
Metadata File
-
Upload the metadata file provided by your IdP.
This is should be available for download in XML format from your IdP, and includes all relevant information such as tenant names and certificates.
IMPORTANT: These fields cannot be changed after they are saved. If you want to change the IdP name or update the metadata, you will need to delete this entry and create a new one.
-
Click Create Identity Provider.
Google
-
Follow these instructions to create a web app to represent PacketFabric: Set up your own custom SAML application.
-
Under step 2, click Download Metadata.
Upload this file in the PacketFabric portal.
See below for additional configuration notes for completing step 3 in the Google web app wizard.
Auth0
First, you must create an Application to represent PacketFabric. You can read more about Auth0 Applications here: Applications in Auth0.
The type of application isn’t important; we used Single-page web application in testing. Then complete the following steps:
-
Select the Addons tab and toggle SAML2 Web App:
-
In the window that opens, select the Usage tab and download the Identity Provider Metadata:
Okta
The process to get the Okta metadata file requires a workaround.
-
Follow these instructions to create an Application to represent PacketFabric: Create a SAML integration using AIW.
-
When you get to the SAML Settings step, you are required to provide a single sign-on URL and an audience URI. Both of these are provided by PacketFabric, but not until after you have uploaded your metadata file.
As a workaround, provide the following “dummy” values. You will need to edit them later:
Single sign on URL:
https://api.packetfabric.com/v2/saml-providers/abcd0123-456e-7d89-01e2-fgh345678i90./acs
Audience URI:
abcd0123-456e-7d89-01e2-fgh345678i90.api.packetfabric.com
-
Complete the feedback step and then click Finish.
-
You are redirected to the Sign On tab for the application. Click Identity Provider metadata.
-
Copy the XML provided and paste it into a text editor. Save this as an .xml file to upload to the PacketFabric portal.
See below for additional configuration steps.
Azure AD
NOTE: At this time, you must manually edit the metadata XML after retrieving it.
Create an application
-
Open the Azure portal and navigate to the Azure Active Directory page.
-
From the navigation menu on the left, select Enterprise applications.
-
Click New application.
-
Click Create your own application.
-
In the panel that opens, enter a name to represent your PacketFabric integration and leave the default selection Integrate any other application you don’t find in the gallery (Non-gallery).
-
Click Create.
-
When the app has been created, first click Users and groups in the side panel and add a user account with which to test your SAML integration.
-
Click Single sign-on in the side panel and select SAML.
-
Click Edit next to Basic SAML Configuration.
-
To get the metadata file correctly populated, you will need to provide temporary “dummy” values that you will edit later:
-
Identifier (Entity ID):
abcd0123-456e-7d89-01e2-fgh345678i90.api.packetfabric.com
Select the checkbox to make this the default and delete the previous value.
-
Reply URL (Assertion Consumer Service URL):
https://api.packetfabric.com/v2/saml-providers/abcd0123-456e-7d89-01e2-fgh345678i90./acs
-
Click Save.
-
Click Edit next to User Attributes & Claims.
-
Click Unique User ID (Name ID).
-
Under Source attribute, select user.mail.
-
Click Save
-
Click Edit next to SAML Signing Certificate
-
Under Signing Option, select Sign SAML response.
-
Click Save.
-
Click Download next to Federated Metadata XML.
Edit the XML file
-
Open the XML file in an editor. It will be easier if you use an editor that can format the XML into a more readable format.
-
Check the IDPSSODescriptor section for a NameIDFormat tag. If it is missing, append the following to the IDPSSODescriptor section:
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
-
Save your changes.
NOTE:
PacketFabric support is not limited to the IdPs listed above; these are only the providers we have been able to test and document.
IdP-side configuration
Once you have created the identity provider entry, click expand to view additional attributes. You will use these when configuring SAML from the IdP side.
- Header row
- Row 2
-
Assertion Consumer Services (ACS) URL
-
This is the endpoint your IdP must redirect to with its authentication response.
There should be a field in your IdP’s configuration interface in which to provide this URL. Depending on the provider, it might be called an Application Callback URL, a Callback URL, a Post-back URL, or an Assertion Consumer Services (ACS) URL.
- Row 3
-
Entity ID
-
A globally unique string that is specific to this PacketFabric IdP entry.
Some IdPs (such as Google) require the entity ID, while others do not.
- Row 3
- Name Identifier Attribute Mapping
- PacketFabric requires that the name identifier attribute is set to
email. Some IdPs set the default name identifier to User ID.
- Row 3
- Response Signing
- PacketFabric requires that the responses are signed. By default, some IdPs sign the assertion but not the response. Some sign both.
IdP-specific configuration notes
Google
Under step three when setting up your web app, configure the following:
-
ACS URL: Copy the Assertion Consumer Services (ACS) URL from the PacketFabric portal and paste it here.
-
Entity ID: Copy the Entity ID from the PacketFabric portal and paste it here.
-
Signed Response: Select this option.
-
Name ID format: Select Email.
Auth0
SAML Settings
Return to the SAML Web App window described above and select the Settings tab. When you are finished, scroll down and click Save.
- Application Callback URL: Copy the Assertion Consumer Services (ACS) URL from the PacketFabric portal and paste it here.
- Settings: Scroll to line 21 and un-comment
signResponse. Set this to true.
SAML Rule
-
Select Rules from the navigation menu on the left.
-
Click Create Rule.
-
Select SAML Attributes mapping.
-
Set the nameidentifier attribute to email.
-
Click Save Changes.
Related links:
Okta
-
Go to the General tab for your PacketFabric application.
-
Click Edit next to SAML Settings:
-
Under SAML Settings, configure the following:
-
Single sign on URL: Copy the Assertion Consumer Services (ACS) URL from the PacketFabric portal and paste it here.
-
Audience URI: Copy the Entity ID from the PacketFabric portal and paste it here.
-
NameID format: Select EmailAddress.
-
Application username: Select Email.
-
Click Next and then Finish.
-
Complete the steps provided here: Assign applications to users
Related links:
Azure AD
-
From the Azure portal, navigate to the page for the application you created to represent PacketFabric.
-
Select Single sign-on from the side panel.
-
Select SAML.
-
Click Edit next to Basic SAML Configuration.
-
Replace the ‘dummy’ values from earlier with the following:
-
Identifier (Entity ID): Copy the Entity ID from the PacketFabric portal and paste it here. Select the checkbox to make this the default.
-
Reply URL (Assertion Consumer Service URL): Copy the Assertion Consumer Services (ACS) URL from the PacketFabric portal and paste it here.
-
Click Save.
Enable SAML and log in
When you have configured the IdP, click Enable.
Instruct your users to click Sign in with SSO when logging in to the PacketFabric portal:
They will be asked to provide their email address and then will be redirected to a unique login page (the User Login URL that is generated with the PacketFabric SAML settings).
User permission groups
When you enable SAML, the following changes take place:
- Existing users: Regular and Read Only
- Regular and Read-Only users will no longer be able to log in through the PacketFabric login page using their PacketFabric credentials. They must go to the User Login URL and use their IdP credentials.
- Existing users: Admin
- For troubleshooting purposes, Admin users can still log in using their PacketFabric credentials via the PacketFabric login page.
- New users
- If a user has not yet been added to your PacketFabric account and they sign in via the IdP, then they are added as a new user with Read Only permissions.
Troubleshooting
Redirect error
The following error appears if the IdP is disabled in the PacketFabric portal:
Whoops, an error occurred while redirecting you to your login page. Please, try again or contact your administrator.
Signed response error
Some IdPs will sign the SAML assertion rather than the response. However, PacketFabric requires that the response be signed.
If this is the case, you will see the following login error:
The Message of the Response is not signed and the SP require it
The IdP should have a configuration setting allowing you to enable signed responses.
Invalid user login
Some IdPs set the name identifier to user_id rather than email.
By default, PacketFabric uses email addresses as user IDs, so the nameIdentifier attribute should be set accordingly.
Look for the following rule in your IdP’s configuration settings and set it to email:
'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier':'email'
The most frequent cause of this error is the metadata missing the following:
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
Note that depending on how your XML file is formatted, you may need to use a prefix on the opening and closing tags. For example:
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
If you have validated that everything in your metadata file is seemingly correct and are still getting this error, open a support ticket by emailing support@packetfabric.com.
Disable and delete an IdP
Click Disable to disable the IdP. When disabled, users cannot sign in through the identity provider.
You are prompted to confirm.
Note: Users who were added by signing in via SAML will lose access to the portal, as PacketFabric does not save their IdP password. To regain access, they can use the password reset action available from the
PacketFabric login page.
Once disabled, you are given the options to delete or re-enable the IdP.