- 1 Setting up SAML Sign-On
- 2 Cryptographic Security
- 3 SAML Provisioning
- 4 Which User is Authorized?
- 5 Sessions
- 6 SAML Troubleshooting
- 7 Sample SAML <Assertion> Document
- 8 Security
Secure Transparent Sign-On is available for Glance Panorama, Glance Screen Share, Glance Device Casting, and Glance Cobrowse.
The Glance Cobrowse service and website is a SAML Service Provider. Glance uses customer-furnished Identity Providers for secure transparent sign-on. Glance services work correctly when sign on is initiated either by the Service Provider or the Identity Provider.
SAML 2.0-compliant Identity Provider services include (among others):
- One Login
- Microsoft Active Directory Federation Services (ADFS)
- Microsoft Azure AD
- CA Single Sign-On (formerly CA SiteMinder)
As of Glance 3.6, Glance’s SAML provides automatic provisioning of new subscribers. If you wish to use automatic provisioning, please contact Glance Customer Success.
Setting up SAML Sign-On
A ten-minute conversation between an administrator and Glance Customer Success ordinarily is enough to answer questions and configure Glance Secure Transparent Sign-On.
A Metadata Discovery Endpoint is needed from your identity provider. This is a small XML file or a URL for fetching the file. You also need to tell Glance the name of the attribute in your SAML protocol to use to identify your users. (See the Provisioning section) An administrator in your organization can obtain this information.
The Glance service provider usually has this Entity ID, but it can be changed if necessary.
The Glance service provider generally has this POST Assertion Consumer Service (ACS) URL. Note, however, that particular identity provider software may require something different.
Your identity provider may require an ACS prefix. It is:
Please enter this information into your identity provider configuration without line breaks. Replace EXAMPLE with the value provided to you by Glance Customer Success.
Glance requires all SAML transactions to take place over TLS-secured (https) connections.
All identity providers cryptographically sign their transactions. The Metadata Discovery Endpoint you provide to Glance specifies the public key necessary for Glance to verify those signatures. Glance supports signatures using the SHA-512, SHA-384, SHA-256, or SHA-1 algorithms. You may choose the algorithm you prefer from among those choices. The identity provider may cryptographically sign the document at either the Reply or Assertion level; Glance accepts either.
Some identity providers also encrypt their transactions. If your identity provider requires encrypted transactions, Glance must provide a public key to you for that purpose.
Glance’s single sign-on provisioning screen is shown here. The best way to obtain values for most fields in this screen is to upload a Metadata Discovery Endpoint XML file. Most identity provider operators can provide it.
SAML Provisioning Fields
Group Number and Name: Identification of the customer group.
Single Sign-On Method: You may choose Off, SAML 2.0, or Encrypted SAML 2.0. Most SAML customers use SAML 2.0 (without encryption).
Description: A text field describing the SAML setup.
Unique Account Identifier: For some identity providers, this must have a specific value. For example, for Salesforce.com accounts, it should contain the Organization ID. For Azure Active Directory accounts, it should contain the Tenant Unique Name. If you set it, you can use its value in the idptoken parameter in Service Target URLs (described later in this document). If it is not required by your identity provider, you may leave it blank.
Operational Status: When you first provision a new account, set this to Provisioning. This setting causes SAML authentication attempts to put entries in the Access Log. When the provisioning is stable, change this to Production.
Redirect for IdP-initiated sessions. Some identity providers allow users to initiate single sign-on directly from the identity provider’s user interface. This value allows you to redirect those users to an appropriate page on the Glance service. For example, /cobrowse/AgentJoin.aspx presents the Cobrowse join page to users coming in via the identity provider. This field must contain a relative URL to a page within the Glance backend. It may not contain an absolute URL: any URL starting with https://.
Entity ID: This is the federation entity ID for the Glance service provider. In most cases it should be set to glance.net/sp/1. Some cloud identity providers will provide the correct value. For example, for Azure Active Directory, it usually is set to the Azure Tenant GUID.
User Identity Attribute Name: Assertions, the tokens sent to Glance from identity providers, contain one or more attributes describing the authenticated user. Put the name of the attribute uniquely identifying the user. The attribute value must uniquely match the Glance user’s Glance Address, Partner User ID, or Email Address.
Metadata Discovery Endpoint: A metadata discovery endpoint is an XML document furnished by the identity provider. You upload it to Glance here. Metadata Discovery Endpoints are very helpful because they set most of the required fields on this provisioning page.
Identity Provider Endpoint URL: This is the URL, furnished by the identity provider, to which Glance presents authentication requests. A Metadata Discovery Endpoint document contains it.
Identity Provider Endpoint Type: Glance presents authentication requests to your identity provider using either https redirect, or an https POST operation. Your identity provider furnishes this value. A Metadata Discovery Endpoint document contains it.
Authentication Context: Most identity providers require elements called authentication contexts when Glance sends single sign-on requests. Others do not allow them. Your identity provider gives you this setting.
Name ID Policy: Most identity providers require an element called a NameID Policy when Glance sends a single sign-on request. In most cases, the NameID Policy should specify an Email, but some identity providers require the policy to be Unspecified. Your identity provider gives you this setting.
ACS Parameter Style: Your identity provider responds to single sign-on requests using a Glance URL called an Assertion Consumer Service (ACS). In most cases, parameters describing what to do after single sign-on can be appended to the ACS. In some cases your identity provider passes those parameters in a separate Relay State element. Your identity provider gives you this setting.
X.509 Public Key: Your identity provider furnishes one or more public keys for Glance to use when validating Assertions, the tokens sent to Glance from identity providers. The identity provider cryptographically signs Assertions with a private key matching one of these public key. Cryptographic signing prevents Assertions from being forged. A Metadata Discovery Endpoint contains the public key or keys. See Changing Public Keys below for more information about these fields.
Encryption Certificate: When you choose Encrypted SAML 2.0 in the Single Sign-on Method, this field appears. When you use Encrypted SAML 2.0 your identity provider responds to single sign-on requests by sending encrypted Assertions (XML tokens) to Glance. This is the key certificate by which Glance decrypts those documents. The key certificate is secret. A Glance staff member generates it and never sends it to the identity provider.
A Glance staff member will upload the key certificate file and then press the Update button. The provisioning page will show the corresponding public key. Provide the public key to the person who operates your identity provider.
Notice that Encrypted SAML is only used to conceal the contents of Assertions. Assertions are already transmitted via https Transport Layer Security. Encrypted SAML provides an extra measure of security beyond https. Most SAML users do not use encryption, but rather rely on https alone.
Changing Public Keys
Glance supports multiple public keys. Each one is used in turn to attempt to validate each SAML Assertion.
From time to time, identity provider operators may replace (rotate) the cryptographic key they use to sign SAML assertions. When this happens it is necessary for the identity provider operator to furnish the new public key to Glance. These steps allow for seamless key-pair changes, without the need to synchronize changes to your identity provider and Glance’s provisioning screen.
- The identity provider operator generates a new public / private key pair.
- Glance puts the new public key into the provisioning screen as an “additional public key.”
- The identity provider operator starts using the new key pair.
Vendor-Specific Provisioning Information
Certain vendors of identity provider servers require specific provisioning; this screen makes it possible.
Microsoft Active Directory Federation Services (AD/FS)
When provisioning AD/FS the metadata discovery endpoint file provides most of the necessary information seamlessly. It may be necessary, however, to set the Authentication Context to “Omit” and the Name ID Policy to “Unspecified.”
Microsoft Active Directory assigns each user a “User Principal Name” or “upn”. It typically looks like an email address — “firstname.lastname@example.org” or similar. To use it, set the User Identity Attribute Name field to:
Microsoft Azure AD
In Azure, the Unique Account Identifier should be set to the Azure Tenant Unique Name. The Entity ID should be set to the Azure Tenant’s GUID, using a value that looks something like this, with dashes, but without curly braces or other punctuation.
User Identity Attribute Name should be NameID.
Authentication Context should be set to “Include.”
Name ID Policy should be “Email.”
Computer Associates Single Sign-On
Some versions of the CA identity provider does not offer metadata discovery endpoint files. You must provide values for the Identity Provider Endpoint URL, the Identity Provider Endpoint Type, and the X.509 Signing Certificate.
It may be necessary to choose “Redirect” for the Identity Provider Endpoint Type.
For Ping Identity, the Name ID Policy ordinarily must be “Email.”
Some Ping Identity providers require a slightly different Assertion Consumer Service:
Metadata discovery endpoint files from Salesforce.com contain the necessary information to configure Glance to use Salesforce.com as an identity provider.
Metadata discovery endpoint files from Onelogin.com contain the necessary information to configure Glance to use Onelogin.com as an identity provider.
SAML Assertions contain both NameID and Attribute data items identifying and describing the user being authorized by your identity provider. Glance uses the NameID data item to identify a user, and also uses the Attribute you specify in the User Identity Attribute Name field of Glance’s provisioning screen.
Glance users have either email addresses or Partner UIDs, or both, registered in our system. We compare the two data items in the SAML Assertion with both Email Address and Partner UID to identify the correct user.
The result of a successful single sign-on transaction (and indeed of any successful authentication to Glance) is a session cookie named GSSNID stored in the user’s browser.
Service Target URLs
Glance furnishes Service Target URLs (STUs) for users to gain access to the Glance Cobrowse service and our website. The endpoints for these URLs use the session cookie to authorize the operation.
STUs require an identity provider identifier. This is the customer’s numeric identifier at Glance. The examples below use a group id of EXAMPLE. Replace EXAMPLE with the value provided to you by Glance Customer Support (this is the Group ID).
Accessing any STU starts a service-provider-initiated sign-on transaction if no user session pre-exists.
To start an interactive session, the STU is this:
To obtain a Login Key for use by native client software, the STU is:
To join a Cobrowse session prompting for the session key, the STU is:
To join a Cobrowse session, when the session key or visitor ID is known ahead of time, the STU is:
In place of idpid=EXAMPLE, you may use idpname=EXAMPLE.When this is done, Glance’s service uses a name rather than a number to look up the group. Replace EXAMPLE with your account’s group name, provided by Glance Customer Support.
In place of idpid=EXAMPLE, you may use idptoken=TOKENVALUE. When this is done, Glance’s service uses the value you place in the Unique Account Identifier field on the provisioning screen.. Replace TOKENVALUE with the name you put into that field. This is suitable for such things as Salesforce Organization IDs and Azure tenant unique names.
In place of idpid=EXAMPLE it is also possible to provide idpusername=USER.glance.net. When this is done, Glance’s service uses the username provided to look up the customer’s group. This option is convenient in cases where the group name is not known but the username is. Replace USER.glance.net with the Glance username (also known as the Glance Address) of a user (any user) in the organization. If you are not sure what value to use, please contact Glance Customer Support.
When you first provision SAML, set the Operational Status to Provisioning. When you do that, a Glance staff member can look at the Access Log and see SAML operations, both successful and failed.
Glance offers a special-purpose STU for troubleshooting SAML.
If you use this STU you should see a page containing diagnostic information. Glance Customer Success can use this diagnostic information to figure out problems.
Problems with Redirection
A user trying to authenticate with SAML may see a text document looking something like this:
This is a Glance login key. If the user did not expect to get a login key, but rather some page within www.glance.net, check whether the STU is correct. If the user did not use an STU, but rather came in via an identity provider initiated session, check the value of Redirect for IdP-initiated Sessions
Time and Clock Synchronization Problems
SAML Assertion tokens expire. It is important that your identity provider server’s time-of-day clock is synchronized to a stratum 3 or better time server. At Glance, we synchronize our server time-of-day clocks to pool.ntp.org, which is in turn synchronized to the stratum 1 time service at the US National Institute of Standards and Technology. If the timestamp in an Assertion doesn’t match the time on our server, the SAML specification calls for us to reject it, and we do. (Timestamps are all in UTC, rather than any particular time zone.)
This kind of problem can occur during prototyping with temporary identity provider installations.
Expiring Assertions make it difficult for cybercriminals to use so-called replay attacks to gain access to services where they do not belong.
Users Not Found
Often, during initial provisioning, your identity provider sends us SAML assertions matching no users in Glance’s system, so SSO logins fail. Mismatches like this can be for several reasons:
- The User Identity Attribute Name is set incorrectly on our provisioning screen.
- Your identity provider is not configured to send the correct attribute.
- The users you send us are not yet provisioned in our system.
- The users you send us have not yet had Partner UIDs assigned to them.
- The users you send us have Partner UIDs that don’t match your identity provider’s user identification. This often happens with badge numbers (employee numbers). For example, consider a user with badge number “00144616.” The identity provider might strip the leading zeros and send “144616” to us in the Badge attribute when the Partner UID for that user in our system is “00144616.” These two versions of the same number do not match.
Examining the output of the troubleshooting STU can help identify these user mismatch issues. So can looking at the Access Log.
Sample SAML <Assertion> Document
The key protocol element in a SAML authentication transaction is passed as an XML document containing an <Assertion> stanza. This is sent from your identity provider to our Assertion Consumer Service, in response to a request from a user. The document asserts—makes a promise—that the user mentioned in it has convinced your identity provider that they are who they claim to be. It also asserts that they are authorized by you to use Glance services.
This is a sample of an <Assertion> document. This particular sample was generated by PingIdentity.com to fulfill an identity-provider originated sign-on request.
In ordinary use, we never need to look at these XML documents. But, during initial provisioning and troubleshooting, it can be helpful to examine one or two of them.
Notice the attribute items—name and value—marked in red near the end of this example. In this case, the user’s email address is used uniquely to identify the user. You need to tell us the name of the attribute your identity provider uses to identify your users.
- The HMAC algorithm is a current best practice for message authentication.
- SHA-2 is a current best practice for hashing and approved by FIPS and other authorities.
- The security of HMAC is dependent on a sufficiently large key value. Glance currently assigns a 128 bit random API key, but a larger key can easily be assigned to any Glance customer.
- In the case that a Login Key is generated with an erroneously long expiration, the customer’s API key can be updated to invalidate any outstanding keys. This is mitigated somewhat by limiting how far in the future expiration will be allowed.
- There is no nonce value in the key that prevents replay attacks. This is because the mechanism is designed to be stateless. The expiration timestamp mitigates this potential concern. The Login Key should be sent over a secure connection. The Login Key is sent between the Glance user (session host or co-browse agent) and Glance. It is not sent to the end guest/visitor.
- The Login Key is intended as a password replacement, not for signing an entire command. It does not include the Session Key and other parameters including display, forward/reverse, and remote control requested.
- There is no three-party authentication as in OAuth. Currently, the usage is for customers or partners to generate their own keys for their own users, using their own API Key.
See the Security section for more information on Security settings.