- Created by John Dougherty on Jan 04, 2021
In This Article
Overview
If an application supports SSO using SAML, you can federate the application with Clearlogin.
If you are unable to find your app in the catalog, you can create a custom SAML app below.
SAML apps require a tight integration with the SSO application and Clearlogin. Additionally, each application vendor implements the SAML protocol in different ways. However, with that said, we will try to cover all of the possible settings required for a successful integration.
Steps to Add a SAML App
- Sign into the Clearlogin Admin Console: https://admin.clearlogin.com
- In the left navigation bar, browse to: Apps
- Click on the New App Connection button
- At the bottom of the page in the Custom Connections section, select the SAML App
- Using the below tables as a reference to enter the required information, and then select Create SAML App
- After saving the SAML application, the summary page will contain the public portion of the signing certificate, which needs to be imported into the SAML application.
The below table describes the different properties included in the signing certificate. To view the specifics of the signing certificate created by Clearlogin for your SAML application, paste it into this certificate decoder: https://www.sslshopper.com/certificate-decoder.html
Certificate Property | Description |
---|---|
Common Name | This will be the URL to your Clearlogin tenant. Ex: https://companyName.clearlogin.com |
Organization | Clearlogin |
Locality | Westfield |
State | New Jersey |
Country | US |
Validity Period | 3 Years |
Issuer | https://companyName.clearlogin.com, Clearlogin |
Serial Number | A randomly generated ID |
SAML APP Connector Settings
General Settings
Setting Name | Description |
---|---|
Display Name | This name will be shown at the bottom of the app tile in the user's dashboard. |
Icon | Upload a custom image file, which will be used in the app tile in the user's dashboard. |
Accepted Access Tags | Bookmark apps support multiple access tags to allow different sets of users access to the web site. Choose the access tags that you would like to allow access to this App Connection.
For more information on Access Tags, refer to the Clearlogin Applications article. |
MFA Access Tags | SAML apps can be configured with per-application MFA. This means a user will need to go through the MFA process when they click on the app tile in the user dashboard. Choose the access tags that you would like to trigger an MFA prompt.
For more information on Access Tags, refer to the Clearlogin Applications article. |
MFA Duration | The length of time to wait after a user has launched an app to prompt for MFA.
|
URL Settings
Setting Name | Description |
---|---|
Login URL (ACS) | This URL is specific to, and provided by, the SAML application. It is known as the Service Provider ACS (Assertion Consumer Service) URL, and is the URL Clearlogin will send the SAML Assertion (token) to. |
Logout URL (SLO) (Optional) | This URL is specific to, and provided by, the SAML application. It is known as the Service Provider SLO (Single Log Out) URL, and is the URL that users can navigate to for terminating their session in the SAML application. |
App URL Override (Optional) | For SP-Initiated login fill in this value with your Service Provider's URL that will begin the SSO process by sending a SAML Request to Clearlogin. Leave this blank for IdP-Initiated login and Clearlogin will send a SAML Response directly to the Login URL. |
Audience
Setting Name | Description |
---|---|
Audience Restriction | If necessary, this URL is specific to, and provided by, the SAML application. If it is not necessary, leave it blank, and Clearlogin will fill this field first with the Audience from the SAML request and second from the Login URL (ACS). |
NameID Value | This is the primary identifier for the username included in the SAML assertion (token). Attribute Placeholders can be used within this field.
|
NameID Format | This is the supported format that the SAML application (Service Provider) expects the NameID to follow. Clearlogin supports the following NameID formats:
|
SAML Namespace | Determines the SAML namespace to use in the signed XML Assertion document. Most SAML applications support the SAML 2 namespace. If so, it is recommended to change the drop-down to SAML2. Otherwise, leave it with the default SAML namespace.
|
Attributes
Attributes are the keys and their associated values that you would like to include in the data sent for authentication. Attribute Placeholders can be used within the value field. See the below SAML Attribute Placeholder Examples section for attribute placeholder examples.
Setting Name | Description |
---|---|
Add Attribute | Use the add attribute button to add a new attribute using a Key/Value pair. The key will be the attribute's name, and the value would be the attribute's value. If you don't add any attribute placeholders, the following are used by default from the user's Clearlogin User Profile:
|
Attribute Format | Indicates to the application how to interpret the attribute names.
|
Minify XML | Enable this setting to compress the size of the XML sent by Clearlogin to the application. Do not enable this setting if the SAML application does not support XML compression.
|
Signing Certificate Properties
Setting Name | Description |
---|---|
Digest Method | This is the hash algorithm used to generate the digital signing certificate, which is used to sign the XML SAML assertion (token) for authentication. If you change the digest method you will need to generate a new certificate in Clearlogin and update the SAML application with the new certificate.
|
Canonicalization Algorithm | The standard used when generating the digital signing certificate. It is recommended to leave this at the default unless the SAML application does not support the #WithComments properties.
|
Additional Settings
Setting Name | Description |
---|---|
Debug App | Enables or disabled debug logging. Enable this to view logs for troubleshooting purposes.
|
Enabled | This will enable or disable the app. When it's disabled, it will not show on the user dashboard.
|
Admins Only | When selected, only user accounts assigned the admin role will see the app on the user dashboard.
|
Hide on Dashboard | When selected, the app will be hidden from the user dashboard.
|
SAML Attribute Placeholder Examples
In addition to hard coded values, you can use the below example Attribute Placeholders to populate fields with information from the authenticating user.
Expand to view examples for each attribute placeholder type.
These are the available placeholders for attributes in your Clearlogin tenant account.
Attribute Placeholder | Description |
---|---|
{{tenant.domain}} | Your configured domain name. |
{{tenant.account_id}} | Your configured Account ID. |
These are the available placeholders for Clearlogin User Profile attribute placeholders.
Attribute Placeholder | Description |
---|---|
{{cl.email}} | The user's email address |
{{cl.username}} | The user's username |
{{cl.name}} | The user's name |
{{cl.first_name}} | The user's first name |
{{cl.last_name}} | The user's last name |
{{cl.role}} | The user's Clearlogin role |
{{cl.access_rules}} | The user's Access Rules |
{{cl.avatar_url}} | URL to the user's Clearlogin avatar |
{{cl.tenant_domain}} | The user's configured domain name |
{{cl.lockout}} | Whether the user is locked out |
{{cl.openid_uid}} | The user's OpenID user id |
{{cl.transient}} | A random unique identifier |
{{cl.persistent}} | A calculated per-user unique identifier |
{{cl.last_sign_in_at}} | Date last signed in at |
{{cl.last_sign_out_at}} | Date last signed out at |
{{cl.ossmosis_user_id}} | The user's Ossmosis user id. Defaults to Clearlogin username/email. |
These are some of the available placeholders for user attributes provided by your Active Directory (LDAP) identity sources.
Attribute Placeholder | Description |
---|---|
{{ldap.mail}} | The user's email address |
{{ldap.sAMAccountName}} | The user's username |
{{ldap.userPrincipalName}} | The user's user principal name (UPN) |
{{ldap.uid}} | The user's login id |
{{ldap.cn}} | The user's canonical name |
{{ldap.gn}} | The user's given name (first name) |
{{ldap.sn}} | The user's surname (last name) |
{{ldap.dn}} | The user's distinguished name |
{{ldap.distinguishedName}} | The user's distinguished name |
{{ldap.memberOf}} | The user's groups |
{{ldap.ou}} | The user's organizational unit |
{{ldap.lastLogon}} | Timestamp of the user's last login |
{{ldap.lastLogoff}} | Timestamp of the user's last logout |
{{ldap.pwdLastSet}} | Timestamp of when user's password was last set |
{{ldap.accountExpires}} | Timestamp of when user's account will expire |
{{ldap.badPwdCount}} | Count of bad password attempts |
{{ldap.badPasswordTime}} | Timestamp of last bad password attempt |
{{ldap.objectGUID}} | Unique identifier for an object |
{{ldap.objectSid}} | Binary value that specifies the security identifier |
These are based on the default attributes for Clearlogin Directory.
Attribute Placeholder | Description |
---|---|
{{cld.email}} | The user's email address |
{{cld.username}} | The user's username |
{{cld.name}} | The user's name |
{{cld.groups}} | The user's groups |
{{cld.avatar_url}} | The user's avatar URL |
{{cld.password_reset_required}} | Whether password reset is required |
Attribute Filters
These filters can be applied to force an operation on the attribute.
Filter | Description |
---|---|
Base64.encode64 | Sends the Base64-encoded version of an attribute Ex: {{cl.email | Base64.encode64}} |
strip_domain | Strips the domain from an attribute Ex: {{cl.email | strip_domain}} |
lowercase | Forces an attribute to lowercase Ex: {{cl.email | lowercase}} |
Transform Rules
Transform Rules allow you to define custom placeholder policies that take a placeholder input and transform it into a different placeholder (or value) output. A Transform Rule will check to see if a placeholder matches one or more conditions, and if conditions are matched, then the Transform Rule will change the placeholder type and/or placeholder value defined by the rule.
A common example is to transform a user's group membership into a specific role within a SAML application. Clearlogin knows the user is a member of the group, but the application doesn't care. The application is only concerned with the user's role assignment within the application.
Lets say George is a member of the Financial Admins group. When George authenticates with the company's financial application he is given the Admin role within the application. This is because the transform rule converted George's group membership into the Admin role of the application.
Transform Rule Settings
Setting Name | Description |
---|---|
Display Name | The name of the transform rule |
Placeholder Name | The name of the placeholder used to call the rule. If left empty, the Display Name will be used. |
Transform Conditions | One or more conditions that must be met to transform the incoming attribute placeholder into a different value or another attribute placeholder. IF this Attribute Placeholder meets the Condition of this Value, then output this Value or Placeholder. Available Conditions
|
- No labels