SAML SSO Configuration

Unvired applications support login via SAML for single sign on with any supported Identity Providers such as Microsoft Active Directory. UDEP supports both SP initiated SSO and IDP initiated SSO.

The required configuration steps are explained in detail,

Microsoft Active Directory Federation Services Configuration

At the Microsoft ADFS the configurations, first add a new Relying Party Trust. Select the option to enter data about the Relying Party manually.

• Type in an appropriate name to display. It is recommended to use the Unvired Application name here for easy identification.
• Select an ADFS 2.0 profile (or later)
• Skip the certificate configuration for now
• Enable support for the SAML 2.0 WebSSO protocol and set the value to the SP_ASSERTION_CONSUMER_SERVICE_URL
• Add the SP_ENTITYID URL as the relying party trust identifier
• Permit all users to access this relying party trust

Now double click the newly added relying party trust to add additional configuration.

• Under endpoints, make sure SAML Assertion Consumer URL binding is set to POST and URL is set to the value configured for SP_ASSERTION_CONSUMER_SERVICE_URL in the SAML configuration below
• Under endpoints, add SAML Logout URL, set binding to POST and URL to the value configured for SP_SINGLE_LOGOUT_SERVICE_URL
• Set the secure hashing algorithm to SHA1 or SHA256 based on configuration in UDEP for the property SP_SIGNATURE_FORMAT
• Under encryption and signature choose the certificate that was copied over from the UDEP and locally created (see UDEP Application Configuration for more details.
• Save

Now edit the relying party to add Claim Rules.

Add a Transform an Incoming Claim rule (Inbound) first.

• Set Incoming Claim Type to E-Mail Address
• Outgoing Claim Type to NameID
• Outgoing NameID format to Email
• Also select Pass Through all claim values and save

Now add a second Send LDAP attributes as Claims rule.

• Choose the attribute store, typically Active Directory
• The following attributes - mapping need to be added:
  • E-Mail-Addresses: E-Mail Address
  • Surname: Surname
  • Given-Name: Given Name
  • Is-Member-Of-DL: Group (if groups checking is used in UDEP)
  • SAM-Account-Name: Windows account name

Configuration is now complete and can be tested.

Tip

To troubleshoot SAML2 errors you can set the com.onelogin loglevel to DEBUG in the Wildfly standalone-full.xml file to get detailed debug logs

ADFS UDEP Application Configuration

The first step to enable SAML SSO is to select the required application and then configure the Application Properties. Under Application Properties select the authentication type as SAML2.

Note

Unvired ID and Email login will be available when SAML is enabled. This allows users without AD credentials or other users to continue to login when the AD system may not be available.

Once the authentication type is set to SAML2, additional SAML configuration options are now enabled. Click on the SAML configuration button to configure the SAML authentication for the application.

Sl.	Property	Details
1.	SP_ENTITYID	Read only. This setting needs to be copied over to the ADFS system for configuration of the Relying Party Trusts.
2.	SP_ASSERTION_CONSUMER_SERVICE_URL	Read only. This is the acs (consumer service) URL to be configured in the ADFS Relying Party Trust.
3.	SP_SINGLE_LOGOUT_SERVICE_URL	Read only. This is the slo (single logout) URL to be configured in the ADFS Relying Party Trust.
4.	SP_CERTIFICATE	Set this to the value of the SP certificate generated for this SP. In addition this certificate file can then be imported in the ADFS relying party trust for the encryption and the signature. See Certificate Configuration section below.
5.	SP_KEY	Set this to the value of the SP Private key generated for the SP certificate earlier. See Certificate Configuration section below.
6.	SP_NAMEID_FORMAT	Select the required NameID format in the dropdown. Recommended value: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
7.	SP_SIGNATURE_FORMAT	Select the required Signature format in the dropdown. Recommended values: http://www.w3.org/2000/09/xmldsig#rsa-sha1 or http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
8.	IDP_ENTITYID	This is the IDP (ADFS) entity id and is similar to a URL like https://<adfs-server>/adfs/services/trust
9.	IDP_SIGNON_URL	This is the IDP (ADFS) sign on URL where UDEP will redirect a login request to and is similar to a URL like https://<adfs-server>/adfs/ls
10.	IDP_SIGNOUT_URL	This is the IDP (ADFS) sign out URL where UDEP will redirect a logout request to and is similar to a URL like https://<adfs-server>/adfs/ls
11.	IDP_CERTIFICATE	The IDP (ADFS) certificate for verification. Copy over the contents of the public key from the CER file of the adfs-server
12.	REDIRECT_URL_WHITELIST	Comma separated list of URLs for redirection after login. Only URLs listed here will be permitted and all other URLs will result in error
13.	CHECK_GROUP	Optional: Comma separated list of Groups to check against for auto provisioning

Tip

The first URL entered in the REDIRECT_URL_WHITELIST will be used to redirect on success or error in case a URL is not specified in the login process. The same URL is also used to redirect in case of an IDP initiated SSO Login request.

How to handle the Login and Logout redirects

Once the login via the IDP is completed the client will receive a redirect to the URL specified. If no URL is specified, the first URL configured in the REDIRECT_URL_WHITELIST above will be used,

• Successful Login: action=login&token=xxxxxxxxxx
• Error Login: action=login&error=Message
• Logout: action=logout

The code in the redirect can handle the action and extract the token in case of success and use the token for subsequent authentication

Using EntraID as your SAML Identity Provider

Login to https://portal.azure.com with your tenant’s Admin credentials.

• Create new Enterprise Application
• Create onw application
  • Enter a name andt hen choose “Integrate any other application you dont find in the gallery”
  • Create
• Click on “Setup Single Sign On”
• Choose SAML
• Basic SAML Configuration
  • Copy the SP_ENTITYID from UMP and paste in Identifier (Entity ID) configuration
  • Copy the SP_ASSERTION_CONSUMER_SERVICE_URL from UMP and paste in Reply URL (Assertion Consumer Service URL) configuration
  • Copy the SP_SINGLE_LOGOUT_SERVICE_URL from UMP and paste in Logout Url configuration
  • Save
• Attributes & Claims - Add any additional claims like GroupID or SAMAccountName (on premises identifier) etc
• From the Setup (your app name) section in Entra ID copy the following.
  • Copy the Entity ID and paste in the IDP_ENTITYID field in UMP SAML Configuration
  • Copy the Login Url and paste in the IDP_SIGNON_URL field in UMP SAML Configuration
  • Copy the Logout Url and paste in the IDP_SIGNOUT_URL field in UMP SAML Configuration
• From the SAML Certifications section in Entra ID download the IDP certificate BASE 64 format
  • Open the BASE64 CER file in an editor and copy all its contents
  • Paste the contents of the CER file into the IDP_CERTIFICATE field in UMP SAML Configuration
• Optional - If you require EntraID also to verify SSO requests then do the following.
  • Follow the SAML Configuration guide above to generate a SP signing certificate.
  • Copy the contents of the certificate into the SP_CERTIFICATE field in UMP SAML Configuration
  • Copy the contents of the key into the SP_KEY field in UMP SAML Configuration
  • Now in the EntraID SSO configuration screen, choose Edit in the Verification Certificates section.
  • Select (Check) the Require verrification certificates
  • Upload the SP certificate you created in step 7 above
• In addition in the Properties in EntraId you can setup a logo and other details as required
  • If you want only selected users to be accessing this app set the “Assignment Required” option to Yes and in the Users & Groups tab select the Users and/or Groups
  • Set “Application is Visible to Users” to Yes and Save
• You are now ready to test your app. Navigate to the Single Sign On page and click on the “Test this Application” button on the top. Test and reconfigure as desired.

Using Google as your SAML Identity Provider

Login to Google Admin using your Google Workspace account (mail id will be your domain and not gmail.com). Goto Apps->Web and Mobile Apps. Click on Add App->Add Custom SAML App to create a new App.

• Enter a name for the SAML Application. It is recommended to use the Unvired Application name here for easy identification
• Enter a description for your reference
• Upload (optional) the App Logo and tap Next
• Copy the displayed SSO URL, EntityID and Certificate. You will use this later to configure in UDEP
• Tap Next to configure the Service Provider (UDEP / Your App)
• ACS URL - Set it to the SP_ASSERTION_CONSUMER_SERVICE_URL from the UDEP SAML configuration above (copy/paste from UDEP)
• Entity ID - Add the SP_ENTITYID URL as the relying party trust identifier from the UDEP SAML configuration above (copy/paste from UDEP)
• Start URL - Leave blank
• NameID - Select Basic Information and Primary Email
• NameID Format - Select Email
• On tapping Next, you will now be prompted for Attribute mapping. You will need to add three attributes.
  • Attribute 1: Choose Primary Email and set App atribute to “emailaddress”
  • Attribute 2: First name and set App atribute to “givenname”
  • Attribute 3: Choose Last name and set App atribute to “surname”
• Save
• The newly created SAML App is now displayed. Click on User Access and either switch the App ON for everyone or use Organizations or select users to provide access

Google UDEP Application Configuration

Configure UDEP according to the UDEP ADFS Configuration above. However the following values will need to be set from the values copied from Google

• IDP_ENTITYID - Paste the value you copied over from Google
• IDP_SIGNON_URL - Paste the value you copied over from Google
• IDP_SIGNOUT_URL - Set to the Signon URL itself
• IDP_CERTIFICATE - Paste the certificate you copied over from Google

SAML Service Provider Certification Configuration

In the SAML Setup, UDEP is the Service Provider (SP). The SP will have an X509 Certificate that is provided to the IDP (Microsoft ADFS for e.g.) to validate if the request is originating from the trusted system.

To configure the UDEP as a SAML SP and provide a certificate, follow the below steps:

1. Generate a certificate/private key pair using openssl and the required algorithm (DSA/RSA). An online creation tool is available on the onelogin site (this is just an reference url, use at your discretion and risk)
2. Once the files are generated, open the certificate in an editor and copy/paste its contents into the SP_CERTIFICATE configuration property (Application SAML Configuration)
3. Similarly, open the private key in an editor and copy/paste its contents into the SP_KEY configuration property (Application SAML Configuration)
4. Also the SP_CERTIFICATE (X509 certificate) needs to be copied over and set in the IDP configuraiton so that requests can be verified by the IDP