Single Sign-On¶
Single sign-on (SSO) refers to the practice of using a single authentication service to log into other services. Skuid’s implementation of SSO uses then XML-based Security Assertion Markup Language (SAML). This authentication protocol is used by many services to allow end users to log into an identity provider (IdP) that grants them access to multiple different services, known as service providers (SP).
With SSO, a log-in process can be IdP-initiated or SP-initiated:
IdP-initiated: Users login once to their IdP, where they enter their unique username and password. Users then select the service they wish to access and are then logged in, without having to enter a username/password for the chosen service.
SP-initiated: User starts at the service provider’s login page and chooses to login using a known IdP.
Alternatively, a user may navigate to a service provider from another portal or hub besides the IdP. They then can then choose to login using a known IdP.
Skuid NLX supports both IdP-initiated and SP-initiated logins. By ensuring users have one method of entry into various services, authentication becomes a more streamlined—and arguably more secure—process.
Both Skuid NLX and Skuid SFX can be used with the SAML protocol. By configuring Skuid for SAML, you can allow your users to login into Skuid with the click of a button. You can also authenticate your end users to data sources used in Skuid pages.
Prerequisites¶
When using SAML to connect to Skuid—or your data sources—the actual screen-by-screen experience will vary depending on which single sign-on services you utilize. Work closely with an administrator who is familiar with SSO as a concept, as well as your identity provider of choice. Included in the collapsed section below is a reference of concepts, phrases, and acronyms commonly seen throughout this process.
Concepts and definitions to know [[]]¶
Single Sign-On (SSO): The actual process of logging into an identity provider to access multiple service providers.
Security Assertion Markup Language (SAML): An XML-based standard for SSO. Skuid only supports SAML 2.0.
Identity Provider (IdP): An application that defines your end users and which applications/services these users are able to access. Examples include:
- Active Directory
- Okta
- Ping Identity
- OneLogin
Additionally services like Salesforce and Google Apps may be used as IdPs.
Service Provider (SP): The services being accessed by the IdP. This can include Skuid, Google apps, Salesforce, or other services.
Assertion: The term used for the XML message IdPs send to SPs to authenticate. Assertions contain several necessary authentication values used for logging in, as well as user provisioning when enabled.
IdP metadata files: A file provided by an IdP describing what is contained within the XML of its authentication assertion. These files contain the following:
- Entity ID: Tells the service provider who the IdP is.
- Certificates: One or more security certificate used for identifying the IdP and encrypting/decrypting SAML messages.
- Single sign-on location URL: A URL that the SP can redirect a user to in order to initiate SSO. If the user has not logged in to the IdP yet, they will be prompted to login, otherwise they will be redirected back to the SP’s ACS URL with an assertion.
Assertion Consumer Service (ACS) URL: The URL where an IdP will send an assertion for an SP to consume and properly authenticate users.
Service Provider Entity ID / Audience URI: The SP entity ID is a unique identifier for a service provider, often written in the form of a URI. Because of this convention, it’s common for this value to also be the service provider’s audience URI, which is states the intended audience of a SAML assertion. Audience URIs are also sometimes referred to as an audience restriction, referring to its use within the AudienceRestriction
tag.
The entity ID and audience URI serve as verification mechanisms to help ensure an assertion is received by the appropriate service provider. Your IdP requires these values to properly send its assertions.
- Skuid NLX uses the same value for an IdP connection’s entity ID, audience URI, and as the location of its service provider metadata. This XML file can be used to simplify registration of Skuid as a service provider in many identity provider systems.
Federated SSO and Federation ID (FID): In federated SSO, the IdP serves as a singular entry point to a group—or federation—of applications. To accomplish this, the IdP and SP will typically communicate a federation ID, which is a trusted piece of data—known to both systems—that can identify individual users.
The SP will receive a federation ID from the IdP, and it will trust that the end user has been properly authenticated. In practice, this means some SPs will not require a password to authenticate a user if it receives the proper FID, and sometimes a password may not even exist.
Within Skuid NLX, users’ federation IDs are set when a user is provisioned and can be updated by Skuid admins at any time.
Creating A New Identity Provider Connection¶
- Navigate to Settings > Single Sign-on.
- Click Create identity provider or, if some IdP connections already exist, click Create in the Identity Providers section.
- Give the IdP connection a name.
- Confirm the name by clicking Create.
The IdP connection details appear in a pending state, as Skuid needs additional information from your IdP to complete the setup. A Setup in progress badge will appear beside the IdP connection while it’s in this state.
Three useful URLs appear for setup within your IdP:
- The Entity ID
- The Assertion Consumer Service (ACS) URL
- The metadata file
These values are used when configuring Skuid as a service provider within your IdP. Typically your IdP only needs your entity Id and ACS URL. Some services allow the use of a metadata file for expedited setup.
Adding identity provider details¶
After initial setup using an entity ID and ACS URL in the IdP, Skuid needs some information from the IdP to complete the connection. Many IdPs provide a metadata file that conveys the other nuances of connecting to that service. Skuid can parse these metadata files by uploading them directly or accessing it via a URL. Finally, it’s also possible (through not typically recommended) to configure these IdP connection values manually.
These settings are configured in the Identity provider details section, after clicking Add details. Details can be added in one of the following ways:
- Import from identity provider metadata file: Skuid uses the metadata file from your IdP to automatically configure all of the necessary fields. Download the metadata file from your IdP and use this option to upload it.
- Import from identity provider metadata file - from specified URL: Skuid will use the metadata file from your IdP to automatically configure all of the necessary fields. Insert the URL that points to your IdP’s metadata file.
- Enter information manually: Configure the necessary IdP details manually.
Using your IdP’s metadata file is the recommended way to create your identity provider connections.
Identity provider details¶
Each IdP connection in Skuid has the following details:
- Entity Id: The unique identifier for your IdP, frequently in URL format. This is sent by Skuid as part of SAML exchanges, and is used by Skuid to validate that a SAML message came from an authorized IdP.
- Login URL: A URL from your IdP that Skuid can use for SP-initiated SSO (i.e. this is the URL that the Login with SAML link on the login screen will go to).
- Logout URL: While neither IdP nor SP-initiated single logout are currently supported, values stored in this property may be used for future single logout enhancements. This value cannot be specified manually.
- Identity provider certificates: Any necessary certificates used to communicate with the IdP service.
Identity mapping¶
Identity mapping tell Skuid how to parse the SAML assertion from the IdP. This allows Skuid to do two things:
Extract a piece of information from the assertion that uniquely identifies the user.
Match this identity information with a corresponding attribute on an existing user record.
If user provisioning is enabled, a new Skuid user is provisioned if the identity in the assertion does not correspond to an existing Skuid user.
Identity mappings are created in a sentence-like format, composed of the following sections:
Subject name identifier / SAML attributes: Determines which piece of information Skuid extracts to identify the user.
Subject name identifier: When your IdP sends a SAML assertion to Skuid in response to a user’s request for SAML identification, this assertion will always include a “Name Identifier” element within a “Subject” statement. Generally, an IdP can be configured so that this Name Identifier element will contain the user’s Skuid username, and most SSO Configs will use this NameIdentifier option.
- with a format of: Determines the format Skuid can expect the name identifier element to take. Select this option based on your IdP’s configuration so Skuid can properly parse the identifier value.
- For more information on name identifier formats, see section 8.3 of the Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 document.
- with a format of: Determines the format Skuid can expect the name identifier element to take. Select this option based on your IdP’s configuration so Skuid can properly parse the identifier value.
SAML attribute: IdPs generally send various attributes about the user, such as the First Name, Last Name, Email, or a Federation Identifier, within various Attribute elements in the assertion. If the NameIdentifier element does not contain the necessary identity information, Skuid will need to identify the user by examining one of these attribute elements.
When selected, a second input appears where you must specify the name of the attribute that contains the desired identification element.
matches Skuid user …: Determines which Skuid user attribute the given information from the IdP should match. Options include:
Username
Federation ID
Email Address
Note
When validating identity based on email address, you cannot have more than one user with the same email address. Skuid cannot reconcile which user to authenticate as, because the email is not unique.
Users who share an email will see errors when logging in via the IdP. Manually update any duplicate emails so that each user has a unique email, or consider using a different attribute for the identity mapping.
User Id
Case-sensitive: Determines whether or not upper/lowercase letters should be recognized as unique.
When enabled,
example
andExample
are treated as unique values.When disabled,
example
andExample
are treated as the same value.
Provisioning¶
The Provisioning tab contains properties and settings related to the management of Skuid user data in relation to IdP user data. This typically involves creating Skuid user accounts when users log in from an IdP, or updating a Skuid user’s account information to match what’s sent in the SAML assertion.
Just-in-time user provision¶
With this property enabled, your Skuid site will automatically generate new end user accounts for anyone that tries to authenticate through your IdP if their account does not already exist.
While the specific process varies depending upon the IdP, user provisioning always requires several attributes be set upon user creation. These attributes can be set via a SAML attribute (<saml:Attribute />
nodes within the <saml:AttributeStatement />
) or as a result of a formula.
Required properties include:
- First Name
- Typically found within an attribute named one of the following:
User.FirstName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- Typically found within an attribute named one of the following:
- Last Name
- Typically found within an attribute named one of the following:
User.LastName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- Typically found within an attribute named one of the following:
- Email: The new user’s email address, to which all user-related communications will be sent. Does not need to be unique.
- Typically found within an attribute named one of the following:
User.Email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- Typically found within an attribute named one of the following:
- Username: Used for logging in to your Skuid site. Must be unique within your site. Ensure that this username follows whatever standardized format you wish to follow on your site.
- Typically found within an attribute named one of the following:
User.Username
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
- Typically found within an attribute named one of the following:
- Time Zone: The user’s time zone.
- Locale: The user’s preferred language/region.
- User type: The Skuid subscription user category the user should be assigned fall into.
- Site permission set name: The site-wide permission set assigned to the user.
- Federation Identifier: Used for uniquely identifying a user across multiple service providers. If not provided separately from username, this will be extracted from the same set of attributes used for username.
- Typically found within an attribute named one of the following:
User.FederationId
User.Username
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
- Typically found within an attribute named one of the following:
How you configure your assertion to include these values will vary from IdP to IdP.
Note
Any end users created through SSO provisioning will not have passwords on Skuid NLX; Skuid authenticates any SSO-provisioned users differently. Therefore they cannot access Skuid NLX any other way than through the IdP (IdP-initiated SSO) or the Login with SAML link on the Skuid Login page (SP-initiated SSO).
Update user properties on login¶
When existing users log in, automatically update properties mapped to SAML attributes and formulas with the latest information from your site’s identity provider. This ensures Skuid user data always matches any updates a user may make to their information in the IdP system.
Reactivate user account on login¶
When enabled, users whose Skuid accounts were previously deactivated will have the accounts reactivated when logging in through this IdP. This allows for pruning of inactive users (for Skuid subscription purposes), while not blocking any users that may eventually log back into the platform.
Certificates¶
By default Skuid does not sign SAML request using a certificate. This behavior can be adjusted in the Certificates tab, which lists the following certificate-related properties:
Request Signing Certificate: For increased security, you can use your Skuid site’s default certificate, or create a custom certificate, sign SAML requests.
Note
Whichever certificate you choose for request signing must be downloaded and uploaded into your IdP’s corresponding service provider configuration. Certificates can be downloaded by going to Settings > Certificates and clicking Download Default Certificate on the certificates table.
Assertion Decryption Certificate: The certificate used to decrypt an encrypted XML assertion from the IdP. You must first create or upload a certificate by navigating to Settings > Certificates, and then return here to select the certificate.
Request Signature Method: Select whether your requests will be signed using the SHA-1 or SHA-256 algorithm.
Logging in via SSO¶
After configuring Skuid NLX and your IdP, both IdP-initiated and SP-initiated SSO are supported.
IdP-initiated: Within your IdP, you’ll configure your Skuid NLX application and access as normal for your particular IdP.
SP-initiated: Once an identity provider connection exists within your Skuid NLX Site’s settings, you’ll see a Login with SAML link on your Skuid site’s login screen.
- If only one identity provider connection exists, clicking this link will log you in directly to Skuid NLX using the one available configuration.
- If more than one identity provider connection exists, clicking this link will display a list of all available SSO providers, so that the end user can select the desired provider.
Session Variables¶
Session variables provide a way to securely access the values of SAML attributes for logic within Skuid. These extracted values are stored securely and only for the duration of the user’s session. Session variables are not tied to individual identity providers; a value must be set for each identity provider connection—enabling their use on sites that have more than one IdP.
These variables are typically used in data source object conditions, which are handled server-side by Skuid NLX, to limit data returned to the client. It’s also possible to make session variables available client-side. This means that the variable can be used in things like display logic or model conditions. If SAML attributes are a useful means of conditional logic for your application, consider enabling client-side availability, but know that savvy end users could access the value of the variable.
For the security conscious, note that session variable values are only accessible during the user’s session, and the values are not visible to the user unless they have been intentionally made available client-side. Skuid does not have direct access to these SAML attribute values, instead passing these values along to Skuid’s other functions strictly for evaluating logic.
Warning
Because session variables rely on SAML attribute values, consider setting single sign-on as the default login method and enabling the Hide username and password login property in the Login screen section.
Users who authenticate through username/password will not have a SAML attribute associated with their session—and thus all conditions based on session variables will fail.
Creating session variables¶
Navigate to Settings > Single Sign-on.
In the Session variables section, click Create session variable / Create>
Configure the variable:
Variable name: The name to refer the variable by.
Values: Set which SAML attribute to use for each identity provider connection.
Warning
Be sure the attribute name exactly matches what is provided in the SAML assertion.
Alternatively, select None - blank value if the IdP does not provide the expected value, though this is typically not recommended. If None is selected, then users logging in through that IdP will typically “fail” any condition using the session variable—such as on data source object conditions. Client-side conditions may see other behaviors.
Available client-side: Makes the session variable available for use in client-side features, like model conditions or display logic. If having the selected SAML attribute available to the user is not acceptable based on security requirements, do not enable this property.
Click Save.
The session variable is created, now available for use within data source object conditions and, if enabled, client-side features.
Using session variables¶
Session variables, by default, can only be used in data source object conditions. Variables can be chosen by setting the Value source to Session variable.
It’s possible to use session variables in some client-side functionality, like display logic, by selecting Session variable as the value source and then choosing the specific variable.
In other instances it’s possible to access session variables through merge syntax:
{{$Session.variable.VariableName}}
This is often useful where applications commonly display user information for personalization. For example, if a page serves as the dashboard for several departments (with the aid of conditional rendering), using a session variable in a Header component could be helpful:
{{$Session.variable.Department}} Dashboard
It’s also possible to run a branch of actions based on whether or not a user’s email contains the domain of an organization.
In this example we’ll display a toast message if the user’s email contains @example.com
. Edit this example to match your expected domain:
Create a session variable named
Email
mapped to the appropriate SAML attribute.Create or navigate to a Skuid page.
Click to edit an Action Framework trigger area.
Click add Add action.
Set the newly created action’s type to Branch.
Edit the branch’s formula by clicking code-block Open Resource Editor.
Enter the following formula:
CONTAINS({{$Session.variable.Email}}, "@example.com")
Click dots-vertical > Add if-true action.
On the newly created if-true action, set the following properties:
- Action type: Show toast message
- Message to display: Confirmed user email!
Click Save.
When the end user activates the trigger area (such as by clicking a button), the branch action checks if the user’s email contains @example.com
. If it does, a confirmation toast is displayed.
This basic example illustrates how client-side session variables can be used to create branching actions. Adjust as needed to suit your use cases.