Implementation > SAML Authentication

Owned by Owain Harris
Last updated: Jan 06, 2022 by Kye Hush
3 min read

ON THIS PAGE YOU WILL FIND:

ON THIS PAGE YOU WILL FIND:

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 user's, 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 is: <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 5 following settings.

SYSTEM VARIABLE

DETAILS

SYSTEM VARIABLE

DETAILS

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 use these options let us know, and we will help you modify them to your requirements.
This is also known as the Assertion Consumer Service URL.

<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.

Some Google SAML terms:
ServiceProvider ID: Is known as ‘Entity ID’
SingleSignOnServiceUrl: Is known as ‘SSO URL’

Under Service Provider Details:

ACS URL: Should be set to ‘https://[THE_URL_FOR_YOUR_WORKBOOK]/api/auth/saml’
Entity ID: Always ‘workbook://app’

Additional Options and Configurations

SAMLConfiguration schema

DISABLING WORKBOOK USERNAME & PASSWORD

There is 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”

 

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

TROUBLESHOOTING

ISSUE

SOLUTION

ISSUE

SOLUTION

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

  • This is caused because the identity 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 matches 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.

 

Related articles

© Tangram 2022. All rights reserved.