SAML

Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between security domains. The Service Provider must enroll with an Identity Provider and obtain an Issuer URL.

How it Works

An enterprise application contains a link to the AgileApps Cloud platform. When a user who has logged on to the enterprise platform clicks the link, he can automatically login to the AgileApps Cloud platform without any additional authentication. For example, if an employee who has logged on the ABC Company corporate website clicks the link to the AgileApps Cloud platform on the landing page, he can login to the AgileApps Cloud platform automatically without requiring a second login.

The following diagram explains the process:

	User	Your organization's web application	Platform	Identity provider
1.	Login to a web app provided by your organization	Provides a link to the platform's SAML handler (generated by the platform when SAML is configured) Includes the desired platform target page as an argument in the link
2.	Clicks the link that goes to the SAML handler
3.			Sends an assertion to the identity provider
4.				Retrieves and validates the user's identity
5.				Sends the user's identity to the platform
6.			Redirects the user to the appropriate page

Enabling SAML

1. Click > Administration > Account Management > Single Sign-On Settings.
2. Click the [Edit] button.
3. Choose SAML from the Single Sign-On Using drop-down list. Selecting SAML automatically displays the Platform Authentication Service URL and the Assertion Consumer Service EndPoint fields below the drop-down list.
4. Fill in the SAML Settings.
5. Click [Save].

SAML Settings

SAML Version

The default SAML version is 2.0

Issuer

This field contains the Identity Provider’s URL. After configuring the Identity Provider for the tenant, copy the URL and paste it in this field. This URL is the SAML-response-issuer-URL.

SAML Third Party authentication URL

This URL is used to authenticate a user or maintain a user's credentials.

• Syntax:The URL and Port Number must be specified using a FQDN or an IP address, for example:

• www.abc.com:9090
• 192.168.1.10
• abc.def.com

SAML Request Issuer URL

This URL is used to access this tenant, for example: http://yourCompany.agileappscloud.com

User Id Type

Determines the type of identifier

• Choose either Platform UserId or Federated Id.

• Platform UserId is the Record Id of the user that is logged in, while Federated Id acts as the user's authentication across multiple IT systems or organizations.

For more information on Federated ID, see Federated Identity

User Id Location

Specifies an attribute tag that defines the location of the User Id

• Choose either Subject or Attribute

Attribute for User ID

Specify the Identity Provider attribute that contains a platform User ID.

Depending upon the settings, either login fails or AgileApps creates a new user, if the User ID attribute is empty, or does not match an existing user.

Create New Users

Check this box to create a new user if AgileApps does not recognize the User ID.

• Attribute for First Name - The name of the SAML attribute that designates the user's first name.
• Attribute for Last Name - The name of the SAML attribute that designates the user's last name.
• Attribute for Email - The name of the SAML attribute that designates the user's email address.

---

• Default User Type - This field is used to specify the type of the user to be created.
• Choose either Platform User or Site User. The platform users are regular users in the platform while the site users have the similar behavior as portal users in the platform.

When Site User is selected as the Default User in this SAML-SSO screen

(a) Only the Default Team is used for user creation. Other settings like default access profile, default application, and default role will be ignored.

(b) The created users will have same default settings as Access Profile (Portal User Profile) and Primary Team (Portal Users and Customers). Meanwhile, the user will also be a member of selected team in Default Team field (or any valid team-name provided through SAML attribute in ‘Attribute for Team’ field).

• Attribute for User Type- This field is used to specify the user-type to be created through SAML attribute. It is SITE for Site User and PLATFORM for Platform User. The Value for this attribute is available in the Identity Provider.

---

• Default Team - This field is used to specify the default Team for the created user. For site users, the team will be a non-primary team.
• Attribute for Team- The name of the SAML attribute that designates the user's default team.

---

• Default Access Profile - This field is used to specify the default Access Profile for the created user. It is applicable only for Platform users.

• Attribute for Access Profile - The name of the SAML attribute that designates the user's access profile. It is applicable only for Platform Users.

The attribute must contain an access profile's record ID.

To get a record ID:

a. Go to > Access Management > Access Profiles

b. Modify the view to display Record IDs and copy the ones you need.

---

• Default Application - This field is used to specify the default Application for the created user. It is applicable only for Platform users.

This setting can be changed in the platform after user login.

The user can change it in their Personal Settings. The admin can do the same in the Users page.

To grant access to additional applications:

a. A user record is created for the user in the platform after login.

b. Use the Application Access page to specify the applications the user can access.

• Attribute for Application - The name of the SAML attribute that designates the user's application. It is applicable only for Platform users.

The attribute must contain the application's record ID.

To get a record ID:

a. Go to > Access Management > Application Access

b. Modify the view to display Record IDs, and copy the ones you need.

---

• Default Role - This field is used to specify the default Role for the created user. It is applicable only for Platform users.

A user record is created for the user in the platform after login.

The user can change it in their Personal Settings. The admin can do the same in the Users page.

You can select multiple roles in this field.

• Attribute for Role - The name of the SAML attribute that designates the user's role in the application. It is applicable only for Platform users.

This field can contain multiple roles separated by _::_

For example, Agent_::_Manager

_

Issuer Certificate

Issuer certificate is used to sign and verify SAML messages. The certificate should be a valid x509 issuer certificate.

• Choose one of the following options:

• Paste the Issuer Certificate in the text area
• Navigate to the Issuer Certificate section, then select and load a file containing the Issuer Certificate

Using SAML

To use single sign-on with SAML, create links that directs you to the platform's SAML handler and pass the desired destination page as an argument.

To create a link to the platform in your enterprise application:

1. Copy the SAML link generated when configuring SAML.
2. Add a done= argument to the link that specifies the target page in the platform.

To create the done= argument:

1. Go to the standard initial page using Service?t=1&targetpage=ViewPort.jsp
2. Go to the page that you want to target
3. Copy the URL from the browser's address bar
4. Edit the URL to remove https://{yourDomain}/networking/
   Now, the URL will have the argument. For example: pages/yourPage.jsp
5. URL encode the link

For more information, see URL Encoding.