SAML SSO Provider Setup

Your Button Dashboard organization can be configured to use a SAML 2.0 Identity Provider instead of Button-local accounts. This document will guide you through setup and configuration.

📘

Button Assistance Required

Activating SAML on your organization requires the assistance of Button's support team. Please review these instructions, then contact your support representative to schedule a call for activation.

Prerequisites

You will need:

• A SAML 2.0 compliant identity provider. Google GSuite, Okta, OneLogin, and many other providers are compatible.
• Administrative access to your identity provider, in order to configure and connect Button.

Step 1: Register Button with your Identity Provider

In your IdP, configure Button as an application. Instructions for this vary by provider. You will need the following information:

• Service Provider EntityID: https://auth.usebutton.com/samlsp
• Assertion Consumer Service (ACS) URL: https://app.usebutton.com/account/login/saml-assertion

Additionally, be sure the user's email address is configured for the NameID field (this is the default for most providers).

Step 2: Provide configuration data to Button

Button needs one of the following:

• Your IdP's setup XML; or
• A metadata URL that resolves it.

Here's an example of what the setup XML looks like:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/example1234">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dev.oktapreview.com/app/button/example1234/sso/saml" />
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://dev.oktapreview.com/app/button/example1234/sso/saml" />
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

Step 3: Schedule an activation call

Because converting your account to SAML-based login can change access unexpectedly, Button asks that you schedule a brief call between our technical support staff and your technical liason. During this call, Button will:

• Verify the configuration you provided us.
• Activate your organization for SAML, based on this configuration.
• Ask you to verify and confirm successful login.
• Troubleshoot any activation issues.

These calls take 30 minutes or less, and can be scheduled with a few days notice. Please reach out to your Button support contact to get a call scheduled.

Frequently Asked Questions

Which style of SAML connection does the app support, IdP initiated or SP initiated?

We require SP initiated login from our login page. IdP initiated login attempts will be redirected there.

Do you require a specific NameID format type (emailAddress, unspecified)?

No, but the NameID value must be the user's email address.

Are there any additional SAML attributes/fields that should be passed along in the SAML assertion from our IdP?

No.

Does the app support Just In Time Provisioning, i.e. if a user does not exist in our account, but we give them access via SSO, then a Button account is created for them the first time they login?

Not currently. Users must be invited to your Button organization either (a) by your Button Partner Success Manager; or (b) by one of your existing Button users with the proper permissions.

Can any role/groups/permisions be assigned through SAML Parameters?

Not currently. Button user permissions must be managed within our app.

Can SSO login be enforced on a user-by-user basis?

No. Once SSO is configured for an email domain, all users with that email domain must login via the IdP configured for that domain.

Does the app allow us to enforce SSO/SAML logins only?

Not currently, but it's on our roadmap. Note that once SSO is configured for your organization's email domain(s), non-SSO login would only be possible for any users invited to your Button organization whose email is not among those configured domains (such as their personal email).

Are user logins globally unique, i.e. if we have separate acccounts setup with Button, can the login to all of them be the same email address?

Yes.

Are SAML configuration settings accessible in the app?

No, they will be configured by a Button support engineer.

Does the app have any user management APIs available which can create, update, delete/suspend user accounts in the system?

No.

In the situation where a user's email/login changes in our directory, what is the downstream effect in Button's app?

Login would be denied unless either (a) the new email was explicitly invited by you, through our interface, on to the team; or (b) the email was changed to that of an already-invited existing address. We can handle such a situation through our support channel, should it arise.

Does Button's SSO implementation support the SAML RelayState functionality for deep linking?

Yes.

What is the session duration, and is it customizable?

If the assertion contains a SessionNotOnOrAfter timestamp, it will be respected. Else, the default SSO session duration is 24 hours.