Configure authentication/SSO

Your users can login to Idealink with almost any SSO provider. This including ADFS, SiteMinder, Ping Federate, and popular OpenID services like Facebook and Google. This article explains how to configure authentication through the web interface, and which protocols and providers are supported.

Login process

Idealink supports almost any SSO provider because it understands the underlying protocols they use (WS-Federation and SAML). The vast majority of SSO providers support WS-Federation or SAML. The general login process is the same for all providers.

Let's say Alice wants to log in using Facebook.

  1. Alice clicks Log in in Idealink.
  2. If multiple SSO providers are available:
    1. Idealink displays a list of available SSO providers (like Facebook or ADFS).
    2. Alice clicks the SSO provider she wants to use.
  3. Idealink redirects her to the SSO provider.
  4. Alice logs into the SSO account (if not already), and is redirected to Idealink.
  5. If Alice doesn't have a profile yet, Idealink lets her create one.

Configuring default SSO

By default, Idealink uses a Planbox SSO provider that supports popular social identity providers (Facebook, Google, Yahoo!, and Windows Live ID). This doesn't require any configuration on your part. You can disable the default SSO provider by configuring your own (see below).

Configuring WS-Federation SSO

You can configure Idealink to accept authentication from any SSO provider that supports the WS-Federation Passive Requestor Profile. This includes ADFS, Azure ACS, Ping Federate, SiteMinder (with the Federation Security Services addon), and many others.

This is the recommended protocol, and other protocols are internally converted into WS-Federation. For more information, see An Introduction to the Windows Identity Foundation for Developers (2009)A Crash Course in Windows Identity Foundation, the Windows Identity Foundation documentation, and the WS-Federation: Passive Requestor Profile specification.

General configuration

To configure WS-Federation SSO in Idealink:

  1. Configure your SSO provider to recognize Idealink as a relying party. Refer to the documentation for your SSO provider.
  2. Configure Idealink by navigating to Admin » System » Settings » WIF Authentication and following the instructions on that page. Warning: the authentication settings are very technical and it's easy to lock yourself out of the system. Before you change these settings, see Regain access to Idealink when SSO is misconfigured below.
  3. Idealink should now accept authentication from your authentication service. If you visit the Idealink login page, your authentication service or its identity providers should be listed, or you should be redirected to your authentication service (depending on your configuration).

On-premise configuration

If you're installing Idealink on your own servers, you can configure more advanced settings by editing Web\web.config file and referring to the User Authentication section, where the relevant settings are documented.

Troubleshooting

Error: Idealink could not retrieve home realm discovery metadata from the configured authentication service.

You have enabled home realm discovery (see §Configuring the authentication service), but an error occurred when Idealink tried to perform discovery.

The full error message includes the URL it tried to retrieve the metadata from, which will often provide a more detailed error message. Visit that URL in your browser and review the following common causes.

Metadata URL returns a specific error message

The error message often includes details on resolving the issue. You may need to refer to the documentation for your authentication service.

Metadata URL returns HTTP 400 (bad request)

Common causes:

  • Your authentication service doesn't recognize Idealink as a relying party. Check the configuration for your authentication service.
  • Your authentication service doesn't recognize the audienceURIs (system.identityModel » identityConfiguration » audienceUris) or realm (system.identityModel.services » federationConfiguration » wsFederation » realm) in the Idealink configuration. Make sure these match the equivalent values in the authentication service relying party configuration.
  • Idealink is misconfigured and sending invalid WS-Federation data. Review your configuration, particularly system.identityModel.services » federationConfiguration » wsFederation.

Metadata URL returns HTTP 404 (page not found)

Common causes:

  • The idealink.authentication » hrd-uri setting is incorrect.
  • Your authentication service does not support home realm discovery. This is an optional extension to WS-Federation.

Metadata URL returns HTTP 500 (internal server error)

An error occurred, but your authentication service isn't configured to display error details. Refer to the documentation for your authentication service for details on enabling error details.

Error: The current WS-Federation identity does not contain any claims that map to the X.

Idealink requires a minimum set of user details (called claims in WS-Federation), but your authentication service didn't provide them in any recognizable form.

Common causes:

  • Your authentication service is providing the required information, but Idealink doesn't recognize it. Add the relevant claim types to the idealink.authentication » claim:* configuration settings.
  • Your authentication service isn't providing the required information. Authentication isn't possible without these minimal claims — your authentication service may be misconfigured. Review the documentation for your authentication service.

Error: There are no configured WS-Federation claims for the X type.

The idealink.authentication » claim:* configuration settings are invalid. Consider restoring them to the default values, which support most known authentication services.

Configuring SAML SSO

You can configure Idealink to accept authentication from SSO providers that support the SAML IdP-initiated POST profile. This includes SSO providers such as Ping Federate and most SSO providers that support SAML (refer to your SSO provider documentation). Idealink supports the common SAML encryption algorithms out of the box (including SHA-512).

This protocol is included for compatibility with older SSO providers — WS-Federation is recommended if your SSO provider supports it (most do).

General configuration

To configure SAML SSO in Idealink:

  1. Configure your SSO provider as needed to send SAML data to Idealink. Refer to the documentation for your SSO provider. Idealink's SAML consumer URL is http://idealink.io/api/SYSTEM_NAME/core/login.saml?replyUrl=http://idealink.io/SYSTEM_NAME&errorUrl=http://idealink.io/SYSTEM_NAME-_/login/LoginError (on-premise URLs may be different).
  2. Configure Idealink by navigating to Admin » System » Settings » SAML Authentication and following the instructions on that page. Warning: the authentication settings are very technical and it's easy to lock yourself out of the system. Before you change these settings, see Regain access to Idealink when SSO is misconfigured below.
  3. Idealink should now accept authentication from your authentication service. If you visit the Idealink login page, your authentication service or its identity providers should be listed, or you should be redirected to your authentication service (depending on your configuration).
  4. Optionally disable the default SSO providers by navigating to Admin » System » Settings » WIF Authentication, and enabling the custom settings without entering any values.

Frequently asked questions

Regain access to the system when SSO is misconfigured

You may be locked out of Idealink if you misconfigure your SSO provider. You can regain access by logging in directly with your secret authentication key.

You can view your secret key in your user profile. Click your username at the top-right, then go to Profile and Security. If you've already locked yourself out of Idealink and don't have your key, contact Planbox for assistance.

Once you have your secret key, go to the following URL to log in: http://idealink.io/SYSTEM_NAME-default/Login/LoginByCode?secretkey=SECRET_KEY. (The URL may be different for on-premise instances.)

Internal authentication services

Idealink supports authentication services located behind a firewall or within an internal network, and doesn't require access to the service. However, there are a few implications:

User access

Users must have access to the authentication service (even if Idealink does not). If they can't visit the service with their browser, they will not be able to authenticate.

You can allow external authentication by letting users link multiple identity providers to their user profile, enabling Idealink's home realm discovery mode (see §Configuring the authentication service) and enabling identity federation in your authentication service (see your authentication service documentation). Users will be able to log in to their same profile with a public identity provider they have linked to their profile when they don't have access to the internal provider.

Configuring custom on-premise SSO

If you install Idealink on-premise, you can configure Idealink to support custom SSO using one of the options below.

Server variables

Idealink can accept authentication by converting server variables into an SSO identity. This enables support for exotic or server-variable-based authentication services.

You must configure two sections in web/web.config:

  • system.webServer » modules:
    Add the following line:
    <add name="ServerVariableAuthenticationModule" type="Idealink.Web.Framework.HttpModules.ServerVariableAuth.ServerVariableAuthModule, Idealink.Web.Framework" />
  • idealink.authentication.serverVariables:
    Set the configuration values in this section by following the included documentation comments.

Forms authentication

Forms authentication (password-protected local accounts) isn't natively supported by Idealink, but you can configure an SSO provider that federates the forms authentication. Forms authentication can be configured via:

Supported SSO providers

The following SSO are known to be compatible with Idealink. This list is by no means comprehensive.

  • Active Directory Federation Services (ADFS) supports WS-Federation. Refer to the Configuring WS-Federation SSO section and the Active Directory Federation Services documentation. ADFS is available in Windows Server and supports identity federation, so you can also support multiple identity providers in Idealink by adding them to ADFS federation. This is the recommended scenario for on-premise installations because it's well-documented and supported by Microsoft.
  • Azure Azure Access Control Service (Azure ACS) supports WS-Federation. Refer to the Configuring WS-Federation SSO section and Identity: Windows Azure Active Directory. Azure ACS is an on-demand cloud service and supports identity federation, so you can support multiple identity providers in Idealink by adding them to Azure ACS. This is the recommended scenario for on-demand installations because it's well-documented and supported by Microsoft. Azure ACS also supports several OpenID identity providers by default (Facebook, Google, Yahoo!, and Windows Live ID).
  • Facebook can be configured via Azure ACS, and is enabled by the default Idealink SSO provider.
  • Google can be configured via Azure ACS, and is enabled by the default Idealink SSO provider.
  • Kerberos can be configured via ADFS.
  • SiteMinder supports WS-Federation through the CA SiteMinder Federation Security Services add-on. Refer to the Configuring WS-Federation SSO section, the SiteMinder documentation, Identity Federation Interoperability – WIF + ADFS + CA SiteMinder, and ADFS Step-by-Step Guide: Federation with CA SiteMinder Federation Security Services.
  • Windows Live ID can be configured via Azure ACS, and is enabled by the default Idealink SSO provider.
  • Windows integrated authentication can be configured via ADFS.
  • Yahoo! can be configured via Azure ACS, and is enabled by the default Idealink SSO provider.

Feedback and Knowledge Base