SAML Authentication

Introduction

SAML (Security Assertion Markup Language) allows you to configure WorkBook to Authenticate its users via an Identity Provider.

Some of these identity providers are

  • Azure AD / Office 365
  • Okta
  • OneLogin
  • AD FS
  • Generic SAML 2.0 Identity Providers

WorkBook expects the claim: “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” to match a users, LoginName in WorkBook.

SAML Authentication is only for password validation, users still have to be manually created and disabled in WorkBook.
It is also not possible to disable regular password authentication at the moment. (A workaround would be to enable LDAP authentication for the user, even if LDAP is not configured)

Configuration on the Identity Provider

The following information is required for you to configure the Identity Provider.

The SAML Binding Endpoints for WorkBook are:

WorkBook Silverlight <schema>://<customer domain>/?SSO=True
WorkBook HTML / Version 9 <schema>://<customer domain>/API/Auth/SAML

WorkBook Supports the following SAML bindings:

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Configuration in WorkBook (Service Provider)

The SAML Configuration is controller via system variables in WorkBook. If you search for “SAML” in the system variables interface you will find the 4 following settings.

1002 / SAML Configuration The configuration for the Service Provider (WorkBook), see below for how to configure
1004 / SAML ServiceProvider Certificate The certificate that WorkBook should use for signing all requests (Not required)
1005 / SAML ServiceProvider Certificate Password Password for the ServiceProvider Certificate
1006 / SAML IdentityProvider Certificate The public certificate for the IdentityProvider, used to validate all requests from the Identity Provider (REQUIRED)
The certificate should be base64 encoded and start with “—–BEGIN CERTIFICATE—–” and end with “—–END CERTIFICATE—–“
1060 / SAML Error Response Redirect Address The address that WorkBook should redirect to if SAML Login fails, #ErrorMessage# can be used as an replacement token

SAML Configuration

A typical SAML Configuration looks like the XML below, if you can’t uses these options let us know, and we will help you modify them to your requirements.

<SAMLConfiguration xmlns="urn:componentspace:SAML:2.0:configuration">
    <ServiceProvider Name="workbook://app" />
    <PartnerIdentityProviders>
        <PartnerIdentityProvider Name="!!ServiceProvider Id!!"
                                Description="IdentityProvider"
                                UseEmbeddedCertificate="true"
                                SingleSignOnServiceUrl="!!URL used for SAML!!"
                                SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                WantAssertionSigned="true" />
    </PartnerIdentityProviders>
</SAMLConfiguration>

Replace !!ServiceProvider Id!! and !!Url used for SAML!!.
If a SAML ServiceProvider Certificate has been specified, change “UseEmbeddedCertificate” to false.

Additional Options and Configurations

SAMLConfiguration schema

Disabling WorkBook Username & Password

There are currently no dedicated way of disabling WorkBook Username’s and Passwords, but there are a workaround involving LDAP authentication and its options.

  1. Enable system variable: “844 / Allow the usage of Lightweight Directory Access Protocol for authentication of users”
  2. On the users you wish to disable WorkBook Username and Password, check the “Is LDAP User”
    iexplore_2016-10-31_10-06-14

This prevents users from using the password assigned in WorkBook, and forces them to use the Identity Provider.

Troubleshooting

The audience restriction * doesn’t match the expected audience restriction *

This is caused because the identify of the application on the IdentityProvider does not match the ServiceProvider.

In general we recommend that you change the identity on the IdentityProvider to match a non existing address, the default sample is “workbook://app”

Login failed for the username: *

This error is issued by WorkBook when no username in WorkBook match the username send by the IdentityProvider.
On most IdentityProvider you can change what it sends as username, and alternatively you can “just” change the username of the individual users in WorkBook.

If the username displayed is a number, guid or similar it is most likely because the system is not sending the claim “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” as expected by WorkBook.

The SAML message doesn’t contain an InResponseTo attribute.

Some IdentityProvider will not send an “InReposenTo” when the login has been initiated by the IdentityService.
If you are unable to, enable this behavior on the IdentityProvider, you can disable it in WorkBook by adding DisableInResponseToCheck=”True” in the PartnerIdentityProvider section of the WorkBook configuration.

Was this article helpful? Useful Useless 0/3 found this article helpful.