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 credentials for institutional users and performs the actual authentication when users log into Aviary.

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

The SSO sign-in sequence

The sign-in sequence follows these steps when a user logs into Aviary with SSO authentication:

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 SSO configuration

There are two requirements for the Aviary SSO configuration to work. Configuring these requirements involves coordinating with the IT staff who administer the IdP at your institution:

A trust relationship: Aviary needs the IdP’s entity ID, sign-in URL, and signing certificate. Aviary reads this information automatically from your IdP’s metadata. The IdP needs Aviary’s metadata URL and callback URL, which can be copied from Aviary and shared with IT staff.

An attribute agreement: A SAML assertion is only useful if Aviary knows which attributes to reference. IdPs may differ considerably in how they name and release attributes.

Aviary can share default attribute mappings that cover common naming conventions and allow institutions to override other settings used by the IdP. This helps to prevent the most common SSO configuration problems , which are caused when attribute mappings don’t match.

What does and does not change with SSO

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

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

Organization roles are still granted deliberately by the Aviary organization for all users signing into the organization through SSO. 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 being 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 are prompted to 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 default Aviary attribute mapping before configuring SSO can save setup and troubleshooting time.

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

The SSO configuration process goes considerably faster if the organization is able to create a test user account in the IdP and share those credentials with Aviary staff. While 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 in the IdP, troubleshooting any problems with the SSO configuration needs to happen indirectly by Aviary staff, organization users, and the IdP administrator. 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 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 name 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 these 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 redirects users from Aviary to be authenticated 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 the 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 the IdP Cert.

⁠

3. Some IdPs publish separate keys for signing and encryption rather than using a single certificate. These 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 using 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 the same value in both fields.

5. When the IdP metadata settings are correct, click the Create Identity Provider button.

6. The Authentication Configurations page will open with the new SSO configuration in the table. However, SSO integration will not be enabled yet. Continue the following steps to finish configuring the integration.

⁠

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 the address with the IdP.

Callback URL: Click the copy icon beside the Callback URL in the table, and share the address 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 attribute statements

The IdP Unique Identification section of the SSO configuration determines whether Aviary can recognize users who are validated by the IdP. Review the IdP Unique Identification section before enabling the configuration. It may be necessary to review this section when working with the IdP administrator to troubleshoot issues with releasing user attributes.

IdP Unique Identification

⁠

These settings let Aviary map and retain identifying information for users validated by the IdP:

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 the IdP and Aviary about the format the identity takes. Two formats are supported (see below).

⁠

Supported Name Identifier Formats:

Format

Description

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

⁠

Attribute statements are the attributes used by Aviary to identify accounts when users authenticate through the IdP. For each attribute statement field, specify the attribute name Aviary should read the value from the IdP’s SAML response.

The values listed in the Defaults column are the attribute names Aviary looks automatically for in the response. If the IdP releases a different value, enter the attribute name in the text box and select Update at the bottom of the page.

Field

Default values Aviary looks for in the response

Notes

Email / Username

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

If the IdP does not release an email attribute, map the 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.

⁠

If the IdP does not release a value that is required by Aviary, the user will be prompted to supply it when they sign in the first time.

⁠

Step 5: Enable and test SSO

Click 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] button. The SSO Group Label is displayed above the button.

⁠

Screenshot 2026-09-10 at 10.40.41 AM.png

⁠

4. Confirm you are returned to Aviary as an authenticated user. A successful sign-in redirects the user back to Aviary with the authentication confirmation. If a user is new to Aviary, they may first be asked to supply any information the IdP does not release.

5. The SSO configuration can be edited at any time. Mappings in particular may need to be updated as attribute agreements with the IdP change.

⁠

Troubleshooting

Configuring SSO can be difficult due to the attribute hand-offs between systems. There are a few common issues to check first when troubleshooting the SSO configuration:

Nobody can sign in at all: Confirm the SSO configuration is enabled and the IdP has registered Aviary’s callback URL exactly as it is 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 the IdP administrator for the exact attribute names that are being released.

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

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

We are glad to help troubleshoot any issues with configuring SSO for Aviary organizations. Please

contact us⁠

for assistance.