1 How SAML Works in Gateway
- 1.1 Verified Identity Providers
- 1.2 When Tokens Expire
2 Implementing SAML
- 2.1 IDSYS SAML Fields
- 2.2 SAML Groups for ACL Policies
3 Troubleshooting SAML
- 3.1 Global SAML Properties

By implementing SAML, users can log in to Swarm browser components (Swarm UI and Content UI) using the exiting credentials from another source — which is known as single sign-on (SSO). SAML (Security Assertion Markup Language) is an open standard that allows identity providers (IdP) pass along authorization credentials to service providers (SP). The popularity stems from the all-around benefits:

User Friendly - SAML simplifies life for users with password elimination, fast logins, and automatically renewing sessions.
IT Friendly - SAML streamlines life for IT with centralized authentication, strong digital signatures, and easy directory integration.

With SAML integration, Content Gateway becomes a Service Provider in the authentication flow, interacting with the IdP to authenticate users. (v7.1)

Version Requirements

For SAML authentication support, upgrade to these or newer versions: Content Gateway 7.1, Content UI 7.0, and Swarm UI 3.0.

How SAML Works in Gateway

While the SAML 2.0 single sign-on (SSO) standard is broad and varied, this section covers only the aspects needed to achieve authentication with Gateway.

Gateway allows use of trusted third-party IdPs to authenticate interactive users for browser use. This is the process:

When a user accesses Swarm UI or Content UI in an unauthenticated browser session, Gateway redirects them to the login page for the identity provider (IdP).
The user authenticates with the IdP.
The IdP redirects back to Gateway with digitally signed proof (the assertion) of successful authentication on success.
Gateway decrypts the assertion, extracts user and group information, and generates a Swarm token.
Gateway redirects back to the original URL with a cookie that carries the token UUID for the rest of the browser session.

Swarm supports these SAML 2.0 bindings:

From Gateway to IdP: both SSO (sign-on) and SLO (log-out) via HTTP-Redirect
From IdP to Gateway: SSO assertions via HTTP-POST, SLO responses via HTTP-Redirect

Only these interactions are supported:

Signed and encrypted assertions from the IdP
Gateway-initiated requests

Verified Identity Providers

Gateway's SAML support has been verified with these leading IdPs. Following are features and differences found among them.

IdP	Features	Limitations

IdP	Features	Limitations
OneLogin	Supports Single Sign-On (SSO) Supports Single Logout (SLO) Supports encrypted Assertions via public/private keypair (). Supports groups via custom attributes
Okta	Supports Single Sign-On (SSO) Supports groups via custom attributes	Partial support for Single Logout (SLO) No public/private keypair support
Google	Supports Single Sign-On (SSO) Requires HTTPS on redirect to Gateway Supports groups via custom attributes	No support for Single Logout (SLO) No public/private keypair support

Configure the IDSYS with an empty URL for SLO if the IdP has incomplete Single Logout (SLO) support. Gateway deletes the token without contacting the IdP upon logout. A subsequent login may not require the user to enter credentials.

When Tokens Expire

Gateway creates a token with an expiring specified by the IdP in the Assertion if authentication with the IdP succeeds. Usually this defaults to 1440 minutes, which is one day.

Gateway falls back to the configured expiration, which is the [gateway] tokenTTLHours if it cannot determine when the session expires from the Assertion. This expiration defaults to one day.

See https://perifery.atlassian.net/wiki/spaces/public/pages/2443810201.

Implementing SAML

As with other types of Gateway authentication (such as PAM and LDAP), a root IDSYS must exist but additional ones can be configured. Add an IDSYS for a specific domain or tenant if single sign-on is desired. See https://perifery.atlassian.net/wiki/spaces/public/pages/2443816807.

Best Practice

Select a strategy to guarantee super users can always gain access in case the SAML method is misconfigured or goes offline if implementing global SSO. These are two approaches:

Company-Wide Tenant for SSO - Assign super users to root-level PAM:
1. Root IDSYS: Using Linux PAM, define super users as Linux users on the Gateway servers.
2. Tenant IDSYS: Using SAML, enable SSO for all users under an organization-wide Content UI tenant (see step 4).
3. Swarm UI access: Grant storage admin access to additional users as needed from the root IDSYS.
Special Domain for Super Users - Assign super users to a domain-level PAM, and have them browse to the DNS host name that matches the storage domain where the PAM IDSYS resides:
1. Root IDSYS: Using SAML, enable SSO for all users via the root IDSYS (see step 3).
2. Domain IDSYS: Using Linux PAM, define super users as Linux users the Gateway servers.
3. Swarm UI access: Grant storage admin access to additional users as needed from the special domain.

The Gateway configuration and the setup required by the IdP need to be completed to enable SAML login capability. None of the Gateway-side configuration requires restarting of Gateway services.

In the administrative portal for the IdP, start setting up SAML to obtain the URLs and public/private keys needed for configuring Gateway.
Root SSO, if applicable:
1. Edit the root IDSYS and configure it for SAML. See IDSYS SAML Fields, below, and https://perifery.atlassian.net/wiki/spaces/public/pages/2443816826.
2. Edit the root Policy and verify it grants the permissions needed.
  See SAML Groups for ACL Policies, below, and help on the .
Tenant/Domain SSO, if applicable: To have separate SSO for specific tenants or domains, complete that setup in the Content UI.
For each tenant or domain,
1. Navigate to Properties (gear icon), and scroll to Identity Management.
  See .
2. Uncheck Inherited and from the Templates drop-list select SAML.
3. Configure the SAML. See IDSYS SAML Fields, below.
4. Obtain the attributes needed to complete the remainder of the setup with the identity provider.
  1. Below the script area, under Identity Provider (IdP) Resources, click the links.
  2. Open, copy, and store the Service Provider Attributes, which include the endpoints needed for assertions and logouts.
  3. Download the XML file version to the right and use that if that service provider can import SAML metadata.
5. Open the Permissions tab and verify it grants the permissions needed.
  See SAML Groups for ACL Policies, below, and .
Back in the administrative portal for IdP, complete any remaining setup using the values and endpoints from Gateway.
Verify single sign-on is working as expected:
1. When a user browses to a storage domain, they see the normal login page unless that domain has a SAML IDSYS (inherited or explicit), which triggers the SAML login process.
  Important: Gateway uses the IDSYS of the storage domain that matches the DNS host name in the URL.
2. If the name they type includes a context suffix (jdoe+tenant or jdoe@domain), the applicable IDSYS is checked.
3. If a SAML login is triggered, the password field is disabled and the Login with SSO button takes them to the identity provider to complete login.

IDSYS SAML Fields

This is the streamlined template filled out to create an IDSYS for SAML in the Content UI, to apply to a tenant or domain. It has fewer fields because the Content UI generates the set of Service Provider ("sp*") fields automatically:

{
  "saml": {
    "cookieName": "token",
    "tokenPath": "/.TOKEN/",
    "entity": "Your root organization Service Provider entity ID.",
    "idpEntityId": "The Identity Provider entity ID.",
    "idpSsoUrl": "The Identity Provider Single-Sign-On (SSO) URL.",
    "idpSloUrl": "The Identity Provider Single-Log-Out (SLO) URL, if applicable.",
    "groupAttrName": "User attribute name where group information can be found, if applicable.",
    "idpCert": ""
  }
}

This is a sample IDSYS.json configuration for authenticating via OneLogin, which shows the Service Provider ("sp*") fields:

{
 "saml": {
   "cookieName": "token",
   "tokenPath": "/.TOKEN/",
   "spEntityId": "https://atomic.com/caringo",
   "spAcsUrl": "http://gw.atomic.com:8888/_admin/saml/login",
   "spSloUrl": "http://gw.atomic.com:8888/_admin/saml/logout",
   "idpEntityId": "https://app.onelogin.com/saml/metadata/9f23...b1cda",
   "idpSsoUrl":"https://caringo.onelogin.com/trust/saml2/http-redirect/sso/9f2...cda",
   "idpSloUrl":"https://caringo.onelogin.com/trust/saml2/http-redirect/slo/125...502",
   "groupAttrName": "group1, group2",
   "idpCert": "MIID3DCC...N8U8nVLp7Ka0="
   "spPrivateKey": "---BEGIN PRIVATE KEY---\nMII...Yts=\n---END PRIVATE KEY---\n"
 }
}

This is how these fields are used and how they differ between a root IDSYS and one created through the Content UI:

All IDSYS Fields	Content UI Template	Source

All IDSYS Fields	Content UI Template	Source
cookieName	cookieName		The name of the cookie that carring the token UUID.
tokenPath	tokenPath		The URL used to create the Swarm token.
spEntityId	entity (used in final generated value)		For the IdP, identifies this particular SAML IDSYS instance. This must be a unique and valid URL. Each must be unique if multiple tenants and domains exist and Gateway is configured with multiple SAML IDSYS instances. Tip: The Content UI generates the final spEntityId value and guarantees uniqueness for the user. A single "entity" value may be reused across tenants and domains.
spAcsUrl	(generated)		After a successful login with the IdP, this is the redirect target, the URL where Gateway receives the Assertion. For any IDSYS other than the root, the URL path must include `/tenant/domain`. This be communicates to the IdP.
spSloUrl	(generated)		After a successful logout from the IdP, this is the URL where Gateway expects a callback. For any IDSYS other than the root, the URL path must include `/tenant/domain`. This communicates to the IdP.
idpEntityId	idpEntityId	IdP	The unique ID of the IdP. This URL comes from the IdP during the administrative setup phase.
idpSsoUrl	idpSsoUrl	IdP	Where Gateway redirects to initiate a login at the IdP. This information comes from the IdP during the administrative setup phase. Always choose `REDIRECT` if the IdP offers both `POST` and `REDIRECT` login options.
idpSloUrl	idpSloUrl	IdP	Where Gateway redirects to initiate a logout at the IdP. This information comes from the IdP during the administrative setup phase. Always choose `REDIRECT` if the IdP offers both `POST` and `REDIRECT` logout options. Leave this blank if the IdP does not support Single Logout (SLO). Gateway deletes the token without contacting the IdP upon logout.
idpCert	idpCert	IdP	The IdP's X.509 public key certificate, encoded as Privacy-Enhanced Mail (PEM). This information comes from the IdP during the administrative setup phase.
wantAssertionsEncrypted			Whether to encrypt the Assertion sent from the IdP. Enabling encryption requires certificates of public/private key configuration. Logins get this error if this is enabled but both parts of the key pair are not configure : `500 Errors detected in SAML settings [idp_cert_or_fingerprint_not_found_and_required]`
spPrivateKey		IdP	Required when encrypting Assertions. Set this to the private key for this SAML IDSYS instance. The IdP must be configured with the matching public key used to encrypt Assertions. The Gateway decrypts using this private key, implementing a trust relationship without the complexity of certificates. Both keys must be configured during the administrative setup phase. Keys must be in Public-Key Cryptography Standards (PKCS) #8 format.
groupAttrName	groupAttrName	IdP	(Optional) List of one or more names to be treated as user group attributes, based on groups maintained by the IdP.
groupSeparator		IdP	Character that separates multiple group attribute names in the list. Defaults to comma.

These fields are also supported in the IDSYS JSON config:

spCert
nameIdEncrypted
authRequestSigned
logoutRequestSigned
logoutResponseSigned
signMetadata
wantMessagesSigned
wantAssertionsSigned
wantNameIdEncrypted

SAML Groups for ACL Policies

To avoid having to name every user, Gateway authorization policies typically refer to groups. To skip manual maintenance of group membership, Gateway automatically assigns the SAML users to groups referenced in policies, and it also allows importing groups. These are the types of groups users can belong to:

Scope	Group Name	Group Examples	About this Group

Scope

Group Name

Group Examples

About this Group

Global

SAMLUsers

Every user authenticated via SAML joins this default group.

Domain

<domain>

gmail.com

Every user who shares the same @<domain> joins a group named for that domain.

jdoe@gmail.com belongs to group gmail.com.

Attribute
(optional)

<attribute>

<attribute>.<domain>

dev

admin

dev.gmail.com

admin.gmail.com

Add attribute names to the Assertions to reference existing groups. Set the field groupAttrNames to a comma-separated list of one or more names.

When an Assertion includes attribute names, each name listed becomes a group that the user joins.

For any group names in the form group@domain, Gateway avoids syntax conflict with Swarm domains by replacing ‘@’ with a period: group.domain.

Group Support

All major IdPs discussed here (OneLogin, Okta, and Google) support groups via these custom attribute names.

Troubleshooting SAML

Edit the configuration to enable SAML-specific debugging:

Edit the global SAML properties file on the Gateway server.
Enable debug mode:
onelogin.saml2.debug = true
No restart of the Gateway service is required; settings are reloaded for each login request.
Repeat these steps to disable debug level once debugging is finished.

Global SAML Properties

Gateway installs with a global SAML properties file that uses the open source toolkit from OneLogin, and it supports deployments to all IdPs. There is no need to use it except for troubleshooting with DataCore Support.

This is a version of the properties file with the comments trimmed out, so the settings it manages can be focused on :

Properties, Trimmed

SP data	Service Provider Data being deployed
onelogin.saml2.strict = true	These are rejected if enabled: Unsigned or unencrypted messages that are signed or encrypted Messages not strictly following the SAML 2 standard
onelogin.saml2.debug = false	Debug mode allows error printing if enabled. Use only during troubleshooting.
[CONFIG] onelogin.saml2.sp.entityid =	Identifier of the SP (service provider) entity, which must be a URI.
[CONFIG] onelogin.saml2.sp.assertion_consumer_service.url =	Specifies info about where and how the `<AuthnResponse>` message must be returned to the requester. This is the URL location where the <Response> from the IdP return to Gateway.
onelogin.saml2.sp.assertion_consumer_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST	Specifies which SAML protocol binding to use when returning the `<Response>` message. For this endpoint, the Toolkit only supports the `HTTP-POST` binding.
[CONFIG] onelogin.saml2.sp.single_logout_service.url =	Specifies where to return the `<Logout Response>` message to the requester, Gateway.
onelogin.saml2.sp.single_logout_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect	Specifies which SAML protocol binding to use when returning the <LogoutResponse> or sending the <LogoutRequest> message. For this endpoint, the Toolkit only supports the `HTTP-Redirect` binding.
onelogin.saml2.sp.nameidformat = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified	Specifies constraints on the name identifier to be used to represent the requested subject. Gateway supports "`unspecified`". An email address is required for SSO login. Other formats are not supported.
[CONFIG] onelogin.saml2.sp.x509cert = [CONFIG] onelogin.saml2.sp.privatekey =	Usually the X.509 certificate and the private key of the SP are provided by files placed at the `certs` folder, but they can be included directly using these parameters. The private key requires `Format PKCS#8 BEGIN PRIVATE KEY`. Convert it with this command if `PKCS#1 BEGIN RSA PRIVATE KEY` exists: `openssl pkcs8 -topk8 -inform pem -nocrypt -in sp.rsa_key -outform pem -out sp.pem`
IdP data	Identity Provider Data to connect with our SP
[CONFIG] onelogin.saml2.idp.entityid =	Identifier of the IdP entity (must be a URI)
[CONFIG] onelogin.saml2.idp.single_sign_on_service.url =	SSO endpoint info of the IdP. (Authentication Request protocol) URL Target of the IdP where the SP sends the Authentication Request Message
onelogin.saml2.idp.single_sign_on_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect	SAML protocol binding to be used when returning the <Response> message. For this endpoint, the Toolkit only supports the `HTTP-Redirect` binding.
[CONFIG] onelogin.saml2.idp.single_logout_service.url =	SLO endpoint info of the IdP. URL Location of the IdP where the SP sends the SLO Request
[CONFIG] onelogin.saml2.idp.single_logout_service.response.url =	(optional) SLO Response endpoint info of the IdP. URL Location of the IdP where the SP sends the SLO Response. The value for `onelogin.saml2.idp.single_logout_service.url` is used if left blank. Some IdPs use a separate URL for sending a logout request and response; use this property to set the separate response URL.
onelogin.saml2.idp.single_logout_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect	SAML protocol binding to be used when returning the <Response> message. For this endpoint, the Toolkit only supports the `HTTP-Redirect` binding.
[CONFIG] onelogin.saml2.idp.x509cert =	Public X.509 certificate of the IdP.
onelogin.saml2.idp.certfingerprint = onelogin.saml2.idp.certfingerprint_algorithm = sha1	Use a fingerprint rather than use the whole X.509 certificate. Generate it with a command (`openssl x509 -noout -fingerprint -in "idp.crt")`, or add the -sha256 , -sha384 or -sha512 parameter. The certFingerprintAlgorithm is required to allow the toolkit to know which Algorithm was used if a fingerprint is provided. Possible values: sha1 (default) sha256 sha384 sha512
Security Settings
[CONFIG] onelogin.saml2.security.nameid_encrypted = false	Whether the nameID of the <samlp:logoutRequest> sent by this SP is encrypted.
[CONFIG] onelogin.saml2.security.authnrequest_signed = false	Whether the <samlp:AuthnRequest> messages sent by this SP are signed. The Metadata of the SP offers this information.
[CONFIG] onelogin.saml2.security.logoutrequest_signed = false	Whether the <samlp:logoutRequest> messages sent by this SP are signed.
[CONFIG] onelogin.saml2.security.logoutresponse_signed = false	Whether the <samlp:logoutResponse> messages sent by this SP are signed.
[CONFIG] onelogin.saml2.security.want_messages_signed = false	Whether the <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> elements received by this SP must be signed.
[CONFIG] onelogin.saml2.security.want_assertions_signed = false	Whether the <saml:Assertion> elements received by this SP must be signed.
[CONFIG] onelogin.saml2.security.sign_metadata =	Whether the Metadata of this SP must be signed. Use either null (for not signing) or `true` (sign using SP private key).
[CONFIG] onelogin.saml2.security.want_assertions_encrypted = false	Whether the Assertions received by this SP must be encrypted.
[CONFIG] onelogin.saml2.security.want_nameid_encrypted = false	Whether the NameID received by this SP must be encrypted.
onelogin.saml2.security.requested_authncontext = urn:oasis:names:tc:SAML:2.0:ac:classes:Password	Authentication context. If empty, no AuthContext is sent in the AuthNRequest. Accepts one or more comma-separated values.
onelogin.saml2.security.onelogin.saml2. security.requested_authncontextcomparison = exact	Allows the `authn` comparison parameter to be set. Defaults to 'exact'.
onelogin.saml2.security.want_xml_validation = true	Whether the SP validates all received XML. Required: `onelogin.saml2.strict = true` must be set to validate the XML.
onelogin.saml2.security.signature_algorithm = http://www.w3.org/2000/09/xmldsig#rsa-sha1	Algorithm that the toolkit uses for the signing process. Options: http://www.w3.org/2000/09/xmldsig#rsa-sha1 http://www.w3.org/2000/09/xmldsig#dsa-sha1 http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 http://www.w3.org/2001/04/xmldsig-more#rsa-sha384 http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
Organization and Contacts
onelogin.saml2.organization.name = onelogin.saml2.organization.displayname = onelogin.saml2.organization.url = onelogin.saml2.organization.lang = onelogin.saml2.contacts.technical.given_name = onelogin.saml2.contacts.technical.email_address = onelogin.saml2.contacts.support.given_name = onelogin.saml2.contacts.support.email_address =

Swarm Documentation

Enabling SSO with SAML