1. Pipe17 Help Center
  2. Organizations & Access
  3. Users & Permissions

Setting up single sign-on (SSO) with SAML

Nazeli Abrahamyan

Single sign-on (SSO) lets your team sign in to the app with the identity provider (IdP) your company already uses, such as Okta, Microsoft Entra ID, or Google Workspace. This article explains how to set up SAML 2.0 SSO: you create a SAML application in your IdP, send Pipe17 your IdP details, Pipe17 completes the connection, and then you verify that sign-in works.

Before you begin

Make sure you have:

  • Admin access to your IdP, such as Okta, Microsoft Entra ID (Azure AD), PingOne, Google Workspace, ADFS, or another SAML 2.0 provider.
  • A way to export your IdP's SAML metadata XML file or signing certificate.

Before you start, agree on these setup details with your Pipe17 onboarding contact:

Detail Provided by Description
Protocol Pipe17 SAML 2.0. This article covers SAML only. If your IdP must use OIDC, tell Pipe17 before you start.
Connection name Pipe17 A name for your organization's SSO connection, usually your company name, for example Acme. Users briefly see it in URLs during sign-in. It can't be changed after it's set.
Email domains You Every email domain that should sign in through SSO, for example acme.com and acme.co.uk. One connection can serve multiple domains, but each domain can belong to only one SSO connection.
IdP-initiated SSO You Yes or no: should users be able to open the app from a tile in your IdP portal, such as the Okta dashboard or Microsoft My Apps?
Existing users to migrate You Yes or no: do users on these email domains already sign in to the app with a password? If yes, tell Pipe17 roughly how many so they keep access after SSO goes live.

Wherever this article shows <CONNECTION_NAME>, replace it with the connection name Pipe17 assigned you.

How it works

Setup happens in three parts:

  1. You configure your IdP. Create a SAML application with the values in this article, then send Pipe17 your IdP metadata. You don't need anything from Pipe17 to start.
  2. Pipe17 completes the connection. Pipe17 sets up the connection on its side, usually within one business day, and emails you when it's ready.
  3. You verify sign-in. Test the sign-in with a user who is invited to the app and assigned to the SAML application in your IdP.

After SSO goes live, users whose email address is on one of your SSO domains sign in through your IdP. Everyone else continues to sign in with a password.

Step 1: Create the SAML application in your IdP

In your IdP, create a new SAML 2.0 application with these values:

Field in your IdP Also known as Value
Single Sign On URL ACS URL, Reply URL, Assertion Consumer Service URL https://auth.pipe17.com/login/callback?connection=<CONNECTION_NAME>
Audience URI Entity ID, SP Identifier, Service Provider Entity ID urn:auth0:pipe17:<CONNECTION_NAME>
Logout URL Single Logout URL, SLO URL https://auth.pipe17.com/logout
Default RelayState - Leave blank

If your IdP imports Service Provider metadata instead of typed values, ask your Pipe17 onboarding contact for a metadata URL. It contains the same values.

Develop environment values

Use these values only if your Pipe17 onboarding contact directed you to the develop environment:

Field in your IdP Value
Single Sign On URL https://auth.develop.pipe17.com/login/callback?connection=<CONNECTION_NAME>
Audience URI urn:auth0:pipe17-develop:<CONNECTION_NAME>
Logout URL https://auth.develop.pipe17.com/logout

Step 2: Configure NameID and attributes

Most failed SSO setups come from these two settings. Configure them carefully when you create the application.

NameID

Send a value that identifies the user: either a persistent ID from your IdP, such as a UUID or object ID, or the user's email address. Set the Name ID format to match:

  • Persistent for an ID.
  • EmailAddress or Unspecified for an email address.

The app checks the user's email address on every sign-in, whichever NameID you send. If a user's email address changes in your IdP, their next sign-in is refused until Pipe17 updates their account. Tell your Pipe17 contact before you change a user's email address.

Attribute statements

Add these attributes in your application's Attribute Statements or Claims section. Attribute names are case-sensitive and must match exactly.

Name Required Value
email Yes. Sign-in fails without it. The user's email address
given_name Recommended The user's first name
family_name Recommended The user's last name
name Recommended The user's full display name

The most common failure is a missing or incorrectly mapped email attribute, for example one sent under a different name or filled from a profile field that's empty for some users. Send the email address in an attribute named email. The address itself can use any capitalization.

Okta

In the application's Attribute Statements section, add:

Name Name format Value
email Unspecified user.email
given_name Unspecified user.firstName
family_name Unspecified user.lastName
name Unspecified String.join(" ", user.firstName, user.lastName)

Microsoft Entra ID (Azure AD)

In the SAML claims section, configure four claims named exactly email, given_name, family_name, and name. Source them from user.mail, user.givenname, user.surname, and user.displayname. Entra ID's default email claim also works for the email address.

Google Workspace

Follow the steps in Set up SSO in Google Workspace below. They cover Steps 1 and 2.

Other IdPs

For PingOne, ADFS, or another SAML 2.0 provider, send four attribute statements named exactly email, given_name, family_name, and name, sourced from the matching fields in the user's profile.

Set up SSO in Google Workspace

Sign in to the Google Admin console as an admin who can add SAML apps, then:

  1. Go to Apps > Web and mobile apps, then select Add app > Add custom SAML app.
  2. Name the app Pipe17, then select Continue.
  3. On the Google Identity Provider details page, select Download Metadata. This is the file you send Pipe17 in Step 3. Select Continue.

  4. On the Service provider details page, enter these values, then select Continue:

    Field Value
    ACS URL https://auth.pipe17.com/login/callback?connection=<CONNECTION_NAME>
    Entity ID urn:auth0:pipe17:<CONNECTION_NAME>
    Start URL Leave blank
    Signed response Leave unchecked (default)
    Name ID format EMAIL
    Name ID Basic Information > Primary email (default)

  5. On the Attribute mapping page, select Add mapping once for each row below, then select Finish:

    Google Directory attribute App attribute
    Basic Information > Primary email email
    Basic Information > First name given_name
    Basic Information > Last name family_name

    You can skip name for Google Workspace.

  6. Open the app and select User access.
  7. Select On for everyone, or turn the app On for the organizational unit or access group that needs the app. Select Save.

For the develop environment, use the develop ACS URL and Entity ID from Step 1.

Keep these points in mind:

  • Google says changes can take up to 24 hours to apply, though usually less. If your first test fails with a Google error soon after setup, wait and try again before changing anything.
  • Don't use Google's Test SAML login button. It starts sign-in from Google, and your connection accepts only sign-in that starts in the app, unless you asked for IdP-initiated SSO. Test as described in Verify sign-in below.
  • Invite users to the app with their primary Google email address, not an alias. The app matches users by the email address Google sends, which is their primary email.

Step 3: Send your details to Pipe17

After you create the application and configure the attributes, send your Pipe17 onboarding contact:

  1. Your IdP's SAML metadata, in one of these forms:
    • A metadata XML file, for example saml2-metadata-idp-<your-app>.xml (preferred).
    • A metadata URL that Pipe17 can open, for example https://<your-domain>.okta.com/app/.../sso/saml/metadata.
    • The individual values: Sign In URL, X.509 signing certificate, and Entity ID.
  2. The email domains that should sign in through SSO.
  3. IdP-initiated SSO: yes or no.
  4. Existing users to migrate: yes or no, and roughly how many. Pipe17 migrates them for you.

Your part of the setup is now on hold until Pipe17 confirms the connection is ready.

What Pipe17 does next

After receiving your metadata, Pipe17:

  • Creates the SSO connection and registers your email domains.
  • Turns on IdP-initiated SSO, if you asked for it.
  • Migrates existing password users on your SSO domains so they keep access after SSO goes live, if applicable.
  • Invites your initial test users to your organization in the app.

Pipe17 emails you when the connection is ready, usually within one business day.

A successful SSO sign-in doesn't create an account in the app. Every user must also be invited to your organization, by Pipe17 or by an administrator in your organization. Administrators invite users from Settings > Users > Invite user. Invite SSO users with the same email address your IdP sends. To learn more, see Managing Users in Pipe17.

Invite User dialog

Verify sign-in

Before you test, make sure your test user is:

  • Invited to your organization in the app.
  • Assigned to the SAML application in your IdP.

To verify SSO:

  1. Open a private or incognito browser window.
  2. Go to app.pipe17.com, or app.develop.pipe17.com for the develop environment.

  3. Enter the test user's email address, then select Continue.

    Pipe17 sign-in page with the Email address field

  4. Sign in on your IdP's page when the app redirects you there.
  5. Confirm that the app opens with the test user signed in.

If sign-in fails, send your Pipe17 onboarding contact the exact error message or a screenshot, the email address you tried, and the approximate time of the attempt.

Troubleshooting

  • Sign-in fails after you authenticate in your IdP
    The email attribute is likely missing or mapped incorrectly. Check that your application sends an attribute named exactly email, filled from the user's email address.
  • A user sees "You do not have access" after signing in to the IdP
    The user isn't invited to your organization in the app. Invite them from Settings > Users, or ask your Pipe17 onboarding contact to invite them.
  • A user can't reach the app from your IdP
    The user isn't assigned to the SAML application in your IdP. Assign the user or their group to the application, even if the application is configured correctly.
  • A user's sign-in is refused after their email address changed
    The app checks the email address on every sign-in. Ask your Pipe17 contact to update the user's account, and tell them before you rename users in the future.
  • Google Workspace shows an error right after setup
    Google changes can take up to 24 hours to apply. Wait and try again before changing the configuration.

Need Help?

If you need additional assistance:

  • Use Ask Pippen, our AI agent, located at the top of the platform page.
  • Submit a support request with as much relevant detail as possible. Learn how to submit a request.

We're here to help you succeed with your operations.

Articles in this section

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.

Have more questions?
Submit a request
Share it, if you like it.