SaaS IdP (SAML) Integration Manual
- Mark Zuk
In the digital age, securing your organization's data and systems is paramount. GYTPOL SaaS stands at the forefront of this mission, offering a robust solution designed to enhance your cybersecurity posture with ease and efficiency. This manual is your comprehensive guide to integrating your Identity Provider (IdP) with GYTPOL SaaS, a critical step in leveraging our platform's full potential to protect your assets.
Identity Providers play a crucial role in managing digital identities and ensuring that access to your systems is secure, seamless, and aligned with your security policies. By connecting your IdP with GYTPOL SaaS, you unlock a synergy that enhances both security and user experience, ensuring that the right people have the right access at the right time.
This manual is structured to guide you through every step of the integration process, from the initial setup to advanced configuration options. Whether you are a seasoned IT professional or new to cybersecurity solutions, our goal is to provide you with clear, concise instructions that make the integration process as smooth as possible.
What You Will Find in This Manual:
Prerequisites for Integration: A checklist of what you need before starting the integration process, ensuring a seamless setup.
Step-by-Step Integration Guide: Detailed instructions on how to connect your IdP with GYTPOLSaaS, accompanied by helpful screenshots and tips.
Troubleshooting and Support: Common challenges and their solutions, plus how to reach out to our support team for further assistance.
FAQs: Answers to frequently asked questions to help clarify any uncertainties you may encounter along the way.
By the end of this manual, you will have successfully integrated your Identity Provider with GYTPOLSaaS, marking a significant milestone in enhancing your organization's security infrastructure. Let's embark on this journey together, towards a more secure and efficient digital environment.
Prerequisites for Integration
Before you begin the integration process of your Identity Provider (IdP) with GYTPOL SaaS, it's essential to have everything in place for a smooth and successful setup. This section outlines all the necessary prerequisites to ensure that you are fully prepared. Please ensure that you have the following before proceeding:
Reply URL and Identifier (Entity ID): These are crucial components that you will use to configure the integration settings in your IdP. The Reply URL, also known as the Assertion Consumer Service (ACS) URL, is where the IdP sends its response after a user has been authenticated. The Identifier (Entity ID) is a unique identifier for GYTPOL SaaS that your IdP uses to recognize our service. Both of these will be provided to you by your GYTPOL SaaS account manager. Make sure to keep these details handy as you go through the setup process.
Sufficient Permissions in Your IdP: To create an application within your IdP that integrates with GYTPOL SaaS, you must have administrative access or sufficient permissions. This is necessary for performing actions such as configuring SAML settings, managing user access, and setting up security policies related to integration. If you are not the administrator, please coordinate with your IT or security team to ensure that you have the appropriate permissions or assistance.
Familiarity with Your IdP's Configuration Process: While this manual will guide you through the general steps for integration, IdPs can vary significantly in their specific configuration processes. Having a basic understanding of how to navigate and make changes in your IdP will be beneficial. If you're unfamiliar, consider reviewing your IdP's documentation or reaching out to their support team for guidance.
Important note: The roles in the GYTPOL UI and the groups in your IDP must be identical, including the same name and case. During authentication, the IDP group token and the role token are exchanged and matched.
Step-by-Step Integration Guide
Azure AD
Add Amazon Cognito as an enterprise application in Azure AD
In this step, you add an Amazon Cognito user pool as an application in Azure AD, to establish a trust relationship between them.
To add new application in Azure AD
Log in to the Azure Portal.
In the Azure Services section, choose Azure Active Directory.
In the left sidebar, choose Enterprise applications.
Choose New application.
On the Browse Azure AD Gallery page, choose Create your own application.
Under What’s the name of your app?, enter a name for your application and select Integrate any other application you don’t find in the gallery (Non-gallery), as shown in Figure 1.
Choose Create.
Figure 1: Add an enterprise app in Azure AD
After creating the application in Azure AD, it may take a few moments for the process to complete. Once finished, you will be automatically redirected to the Overview page for the newly added application.
Please note that there is a possibility of encountering a Not Found error during this step, even if Azure AD has successfully created the new application. In such cases, you can navigate back to Enterprise applications in Azure AD and search for your application by its name to locate it.
To set up Single Sign-on using SAML
On the Getting started page, in the Set up single sign on tile, choose Get started, as shown in Figure 2.
Figure 2: Application configuration page in Azure ADProceed to the next screen and select SAML.
In the middle pane, navigate to the Basic SAML Configuration section, and click on the edit icon.
In the right pane, within the Basic SAML Configuration, replace the default Identifier ID (Entity ID) with the Identifier (Entity ID) provided by your account manager. Then, in the Reply URL (Assertion Consumer Service URL) field, input the Reply URL provided by your account manager, as depicted in Figure 3. Click on Save to confirm the changes.
In the middle pane under Set up Single Sign-On with SAML, in the User Attributes & Claims section, choose Edit.
Choose Add a group claim.
On the User Attributes & Claims page, in the right pane under Group Claims, select Groups assigned to the application, leave Source attribute as sAMAccountName, as shown in Figure 4.
Expand the Advanced options mark the “Customize the name of the group claim” checkbox. Write “groups” in the Name field, as shown in Figure 4 and Choose Save. This will allow automatic GYTPOL roles mapping to Azure AD groups.
Scroll down to the SAML Signing Certificate section and copy the App Federation Metadata URL by choosing the copy into clipboard icon (highlighted with red arrow in Figure 5).
Please send the URL to your account manager.
Assign the application to the relevant groups.
Please note that the roles in the GYTPOL UI and the groups in your IDP must be identical, including the same name and case. During authentication, the IDP group token and the role token are exchanged and matched.
Okta
Configure SAML integration for your Okta app
Create a new App Integration and select SAML 2.0
Under General Settings, enter a name for your app.
(Optional) Upload a logo and choose the visibility settings for your app.
Choose Next.
Under General, for Single sign on URL, enter the Single sign-on URL provided by your account manager (as Reply URL) and Audience URI (SP Entity ID) which was also provided by your account manager, as shown in Figure 2.
Under Attribute Statements (optional), add a statement with the following information, as shown in Figure 3:
Name | Value |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | user.email |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | user.lastName |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | user.firstName |
For all other settings on the page, leave them as their default values or set them according to your preferences.
Choose Next.
Choose a feedback response for Okta Support.
Choose Finish.
Open the application and under the Sign On page, copy the Metadata-URL and send it to your account manager, as shown in Figure 4.
Assign a user to your Okta application
On the Assignments tab for your Okta app, for Assign, choose Assign to People.
Choose Assign next to the user that you want to assign.
Note: If this is a new account, the only option available is to choose yourself (the admin) as the user.Choose Save and Go Back. Your user is assigned.
Choose Done.
Please note that the roles in the GYTPOL UI and the groups in your IDP must be identical, including the same name and case. During authentication, the IDP group token and the role token are exchanged and matched.
Google Workspace
Create Web App
Begin by creating a new web application.
Provide a name for the application.
Download the metadata XML file and then upload it to a publicly accessible URL. Please share the URL with your designated account manager at GYTPOL.
On the subsequent page, fill in the ACS URL with the Single Sign-On (SSO) URL provided by your account manager, along with the Entity ID, also provided by your account manager.
Adjust the Name ID format to EMAIL.
Map the primary email to the claim URL:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.Map the First name to the claim URL:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname.Map the Last name to the claim URL:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname.
To map Google Workspace groups to GYTPOL roles, follow these steps:
Select the desired groups under "Google Groups".
Change the "App attribute" to "groups" (lowercase).
Once completed, click on "Finish" to save the changes.
To assign the web application to your users or groups, follow these steps:
Navigate to your newly created web application.
Click on "User access".
Choose the group or users you want to enable the GYTPOL app for, then check the ON checkbox to activate it.
After selecting the desired group or users and activating the GYTPOL app by marking the ON checkbox, click on the SAVE button to confirm your changes.
PingFederate
Integrating Ping Federate with another application involves several steps. These steps assume that you have already received the Reply URL (Assertion Consumer Service URL) and Entity ID from GYTPOL.
Here's a general outline of the process:
Set Up PingFederate as an Identity Provider (IdP):
Log in to the PingFederate administrative console.
Create an IdP Connection:
Navigate to the "Identity Provider" tab.
Select "Create New" under "SP Connections".
Choose "Browser SSO Profiles" and proceed with the "Next" button.
Basic Information:
Enter a connection name and an optional description.
Click "Next".
Connection Type:
Select the connection type. Choose "Browser SSO Profiles".
Click "Next".
Import Metadata:
Select "Manual Configuration" and click "Next".
Configure the Connection:
Connection Options:
Choose SAML 2.0 and proceed.
Connection Configuration:
Enter the Entity ID (e.g.,
urn:amazon:cognito:sp:eu-central-1_q1W2e3R4).Enter the Assertion Consumer Service (ACS) URL (Reply URL) (e.g.,
https://gytpol-saas-tenant-name.auth.eu-central-1.amazoncognito.com/saml2/idpresponse
SAML Profiles:
Enable the SAML profiles required (e.g., SP-initiated SSO).
Assertion Lifetime:
Set the assertion validity period (default is usually sufficient).
Signature Policy:
Configure signing options based on SP requirements.
Attribute Mapping:
Map the attributes from your IdP to the attributes expected by the SP. Common attributes include names, email, and others. Please refer to the below screenshots for reference.
Click "Next".
Summary:
Review the configuration and click "Done" to complete the setup.
Configure Authentication Policies:
Define the authentication policies for the IdP connection, such as allowed authentication methods, multi-factor authentication, etc.
Publish the Connection:
Ensure the connection is activated and published.
Test the Connection:
Test the SSO flow by initiating a login from GYTPOL login page.
Adjust as Necessary:
If there are issues, check logs and adjust the configuration as needed.
Please see the troubleshooting steps below if necessary.
These steps provide a general framework for integrating PingFederate with GYTPOL using SAML 2.0. The exact steps and configuration details may vary based on the specific requirements of your organization.
Troubleshooting and Support
Once your account manager confirms that the configuration is complete on our end, you can proceed to log in to your application. Simply click on the name of the provider on the login page to initiate the login process.
Login loop
To troubleshoot, open the developer tools by either pressing F12 or right-clicking on the page and selecting "Inspect".
Navigate to the Network tab.
Proceed with the login process until you return to the login page.
You should now be able to locate the row labeled "?error_description" in the developer tools.
Click on the row labeled "?error_description" and navigate to the Payload tab. You should then see the reason for the loop. (Hint: It often relates to the email statement).
In our example, the reason for the loop may be due to the absence of the email statement. (The image example is from Okta).
Groups to GYTPOL roles does not work
When automatic mapping fails, it typically indicates that the IdP did not send the groups in the SAML response.
To troubleshoot this issue, open the developer tools by either pressing F12 or right-clicking on the page and selecting "Inspect”.
Navigate to the Network tab.
Proceed with the login process. Then, click on the row labeled "token".
Navigate to the Preview tab. Copy the value of the id_token.
Visit https://jwt.io/ in your browser and paste the copied value into the provided field.
In the decoded part, check if there is a "custom:groups" field in the payload.
If the "custom:groups" field is missing, ensure that the IdP groups claim or statement is configured correctly.
In Okta, this may involve double-checking the filter (explanation on Regex filtering). In AzureAD, verify if groups are configured to sAMAccountName and ensure that the claim name is correct.
FAQs
I've set up a role using an IdP group name, and users can successfully log in. However, when I check the role, it doesn't display any members.
Correct. Upon user login, the groups are included in a JWT sent to the backend. We then map the user's group to GYTPOL Roles internally. As a result, the user will have the permissions associated with the role but will not be listed as a member of the role.
My IdP does not supply Metadata URLs and only allows me to download the file, what should I do?
Download the file and send it to your account manager without making any edits. We'll take care of the rest.
I want to add a user from my IdP to a role I created but I don’t see the user in the dropdown.
Correct. For GYTPOL to register the user in the database, the user needs to log in to the system first. After that, you'll be able to see them in the dropdown menu.
Can users be created automatically in GYTPOL once we assign the application to them?
No, unfortunately we do not currently offer support for SCIM.
I was assigned the application and was able to login, how ever I am seeing a blank screen
This situation occurs when there are roles configured in the GYTPOL application, but you haven't been assigned to any role.
When attempting to access the application from the application tile, you're encountering an error message indicating "Invalid samlResponse" or "relayState" from the identity provider.
We do not support IdP initiated logins, only logins initiated from GYTPOL are accepted.