Configure SSO for Organizations

Aviary organizations can configure single sign-on (SSO) authentication for users to sign in with their existing institutional credentials, rather than creating and managing a separate Aviary account.

Aviary currently supports the SAML 2.0 SSO protocol. As additional SOO protocols are supported, this documentation will be updated.

The following information details how SAML 2.0 authentication works in Aviary and the steps organizations can follow to configure SSO.

SSO authentication is included as a standard benefit for organizations with Enterprise and Sustaining Partner subscription plans. Configuring SSO authentication carries an additional fee for organizations with other Aviary subscription plans.

See the

Aviary Pricing⁠

page for SSO configuration costs and

Contact Us⁠

for more details about adding it to your subscription.

⁠

How SAML 2.0 authentication works in Aviary

SAML 2.0 (Security Assertion Markup Language) authentication is an open standard that allows an institution’s central login system to verify users accessing an outside application. Two parties participate in SAML 2.0 authentication:

The Identity Provider (IdP) is the system operated by an institution to authenticate users — e.g. Shibboleth, Okta, Microsoft Entra ID, PingFederate, or ADFS. The IdP stores institutional credentials for users and performs the actual authentication when users log into Aviary.

The Service Provider (SP) is the application users want to reach. In this example, Aviary is the service provider.

The SSO sign-in sequence

The SSO authentication process follows a sign-in sequence according to these steps:

A user navigates to an organization’s Aviary site and selects the SSO login button.

Aviary redirects the user to the organization’s IdP target URL.

The organization’s IdP service authenticates the users’s credentials, including multi-factor authentication if required by the institution.

The IdP service returns a signed SAML response to Aviary’s callback URL. The signed SAML response contains an assertion that identifies the user and carries attributes from the IdP to the SP.

Aviary validates the assertion against the IdP certificate published in the organization’s metadata. Aviary reads the NameID and other attributes from the assertion. Aviary then matches those attributes with an existing Aviary user account or creates a new user account.

After Aviary matches the attributes with an existing user account or creates a new user account, the user is signed into Aviary and provided access according to the organization’s permissions.

Requirements for the SSO configuration

Two things have to line up for this to work, and both require coordination with whoever administers your IdP:

A trust relationship. Aviary needs your IdP’s entity ID, sign-in URL, and signing certificate — all of which Aviary reads automatically from your IdP’s metadata. Your IdP needs Aviary’s metadata URL and callback URL, which you copy out of Aviary and send across.

An attribute agreement. A SAML assertion is only useful to Aviary if Aviary knows which attribute in it carries the email address, which carries the given name, and so on. IdPs differ considerably in what they release and what they call it. Aviary ships default mappings covering the most common conventions, and lets you override any of them when your IdP uses something else. Most SSO configuration problems are attribute problems.

What does and does not change with SSO

SSO governs how user accounts are verified when signing into Aviary. It does not grant users access to any restricted content in an organization without additional permissions.

Signing in through SSO makes someone a registered Aviary user. Registered Aviary users can see public content and resources organizations make accessible to logged-in users.

Organization roles for users — Organization Owner, Organization Admin, Organization User, Assigned User — are still granted deliberately by the Aviary organization from the Users page. See the

Manage Users⁠

page for more information.

The process of inviting users to an organization differs when using SSO. A user must sign into Aviary using SSO at least once before they are invited to join the organization as an organizational user.

Aviary organizations may configure more than one SSO integration. Each SSO integration appears as a separate login option when users log into the Aviary organization.

⁠

Before configuring SSO

Gather the following information before configuring SSO for an Aviary organization:

IdP metadata: Either an IdP metadata URL that can be accessed by Aviary or an Entity Descriptor XML file that can be uploaded to the Aviary organization.

An organization contact who administers the IdP: The contact will need to register Aviary as a service provider and confirm which attributes will be released by the IdP.

A list of attributes released by the IdP (if available): Comparing the IdP attribute list with the Aviary defaults before configuring SSO can save setup and troubleshooting time.

Recommended: Create a test user account for Aviary staff in the organization’s IdP

The SSO configuration process goes considerably faster if the organization is able to create a test user account in their IdP and share the account’s credentials with Aviary staff. This is not required, but it is the most helpful step an organization can take to expedite the SSO configuration process.

Without a test user account, problems with the SSO configuration need to be troubleshooted indirectly by Aviary staff, organization users, and the IdP administrator, which may take multiple days per issue. With a test user account, Aviary staff can reproduce and identify the issue directly, read the SAML response, and work with the IdP administrator to make changes quickly.

If necessary, test user accounts can be disabled or deleted from the IdP once the SSO configuration is confirmed to be working.

⁠

Step 1 — Create the authentication configuration

1. Sign in to Aviary and expand the Integrations tab in the admin menu. Click the Authentication Configuration link in the Integrations dropdown menu.

2. The Authentication Configuration page will open. Click the Add Configuration button at the top of the page and select SAML 2.0 from the dropdown menu.

⁠

3. The Create Identity Provider form will open.

⁠

Complete the required naming fields on the Create Identity Provider form:

Field

Description

IdP Name

The custom label shown in the Aviary interface when a user signs in through the SSO integration. Most organizations use the institution or IdP name.

SSO Group Label

The custom label that tells SSO users which option to use when logging in. It is displayed as “[SSO Group Label] Users” above the SSO login button, and “Non-[SSO Group Label] Users” above the standard login form. If left blank, the SSO Group Label defaults to the IdP Name.

⁠

Then include the organization’s IdP metadata on the Create Identity Provider form, using one of the two options:

Field

Description

IdP Metadata URL

The metadata URL from the IdP. If the URL is valid, the IdP Metadata Settings will populate automatically on the form after clicking out of the IdP Metadata URL text box.

IdP Metadata XML

Upload an XML file of the entity descriptor metadata from the IdP. If the XML file is valid, the IdP Metadata Settings below the field will populate automatically after uploading the file.

⁠

Step 2 — Review the IdP metadata settings

Aviary automatically populates the IdP metadata settings based on the information provided in the IdP Metadata URL or XML file.

1. Expand the IdP Metadata Settings section by clicking the + icon.

2. Review and correct any fields before continuing with the IdP configuration. All of the IdP metadata fields can be manually edited if the imported metadata is incorrect.

Field

Description

IdP Entity ID

The unique URI identifying the SAML identity provider. This is often the same as the IdP Metadata URL.

SSO Target URL

The URL that users are redirected to from Aviary to be authentication by the organization’s IdP.

IdP Cert

The organization’s IdP certificate. This may be optional, depending on the type of certificate the IdP uses. The IdP Cert field is populated automatically when it is present in the metadata. If the IdP Cert Multi fields listed below contain values, the IdP Cert field will likely be empty.

IdP Cert Fingerprint

The IdP certificate fingerprint. This may be optional, according to the same terms as IdP Cert.

IdP Cert Fingerprint Algorithm

The algorithm used to compute the IdP certificate fingerprint. This may be optional, according to the same terms as IdP Cert.

⁠

3. Some IdPs publish separate keys for signing and encryption rather than a single certificate. The separate keys are populated from the IdP metadata and displayed in the IdP Cert Multi fields.

Field

Description

Signing

The value found within the KeyDescriptor use='signing' IdP metadata element.

Encryption

The value found within the KeyDescriptor use='encryption' IdP metadata element.

⁠

4. A signing key is required. Aviary validates the SAML response the signing key. An encryption key is optional and may be the same certificate as the signing key. If the IdP publishes a single key that serves both purposes, enter that same value in both fields.

5. When the IdP metadata settings are correct, click the Create Identity Provider button. The Authentication Configurations page will open with the new SSO configuration in the table. However, SSO integration will not be enabled yet.

⁠

Step 3 — Share Aviary URLs with the IdP

The IdP administrator needs two URLs from Aviary before the SSO integration can be enabled. The IdP administrator will use these URLs to register Aviary as a service provider and configure which attributes are released to Aviary. Both URLs are available in the Authentication Configuration table:

Metadata URL: Click the Metadata button in the Actions column to load Aviary’s metadata in your browser. Copy the URL from the browser’s address bar and share it with the IdP.

Callback URL: Click the copy icon beside the Callback URL in the table and share it with the IdP. The Callback URL is the endpoint where the IdP posts the SAML response. Some IdPs refer to it as the Assertion Consumer Service (ACS) URL or the reply URL.

⁠

Step 4 — Configure unique identification and attributes

This is the section that determines whether Aviary can actually recognize the people your IdP sends. Review it before enabling the configuration, and expect to revisit it as you negotiate attribute release with your IdP administrator.

IdP Unique Identification

⁠

These settings let Aviary map and retain a person’s identifying information.

Field

Description

Name Identifier / NameID

The element identifying the subject of a SAML assertion — the person being authenticated. It corresponds to saml:Subject › saml:NameID in the assertion. Most service providers use the user name as the name identifier. Aviary maps NameID to username.

Name Identifier Format

Aligns expectations between your IdP and Aviary about the form the identity takes. Two formats are supported (see below).

⁠

Supported Name Identifier Formats:

Format

Meaning

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

The Subject NameID from the IdP uses the email address format. This is the default.

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

The Subject NameID from the IdP can be any format.

⁠

Attribute Statements

⁠

These are the attributes Aviary uses to identify accounts when people authenticate through your IdP. For each field, specify the attribute name from your IdP’s SAML response that Aviary should read the value from.

The values listed in the Defaults column are the attribute names Aviary looks for automatically when they are present in the response. If your IdP releases something different, enter the attribute name you need in the text box and select Update at the bottom of the page.

Field

Defaults Aviary checks for

Notes

Email / Username

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, email, emailAddress, EmailAddress, Email, mail

If your IdP does not release an email attribute, map your NameID or username attribute here instead.

First Name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, GivenName, first_name, givenname, given_name, givenName

Last Name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, family_name, last_name, LastName, surname, lastname

Group

memberof

Optional.

⁠

Where your IdP does not release a value Aviary needs, the person will be prompted to supply it themselves the first time they sign in.

⁠

Step 5 — Enable and test SSO

Select Enable beside the configuration in the Authentication Configurations table.

Open the Aviary organization’s login page. Each enabled SSO endpoint appears as a Login with [IdP Name] SSO option, grouped under the SSO Group Label you set.

⁠

Screenshot 2026-09-10 at 10.40.41 AM.png

⁠

A successful sign-in redirects the person back to Aviary with the authentication confirmation, which Aviary registers before granting access. If a person is new to Aviary, they may first be asked to supply any information your IdP does not release.

You can return to the table to edit the configuration at any time — mappings in particular, as your attribute agreement with your IdP evolves.

⁠

Troubleshooting

Configuring SSO can be difficult, largely because of the attribute hand-offs between systems. A few things to check first:

Nobody can sign in at all. Confirm the configuration is enabled, and that your IdP has registered Aviary’s callback URL exactly as copied.

People authenticate but arrive as new accounts each time. The Email/Username mapping is likely reading an attribute that changes between sessions, or is absent from the response. Ask your IdP administrator for the exact attribute names being released.

People arrive without names. Your IdP is not releasing given name and surname under any of the default attribute names. Either have those attributes released, or enter the names your IdP uses in Attribute Statements.

Signature validation fails. Check whether your IdP publishes a single certificate or separate signing and encryption keys, and confirm the corresponding fields are populated.

We are glad to help if you run into problems. Contact us at

aviary@weareavp.com⁠