Configure SSO for your Site

Aviary organizations can allow their members to sign in with the credentials they already use at their institution, rather than creating and managing a separate Aviary password. This page explains how single sign-on works in Aviary and how to configure it. Aviary currently supports SAML 2.0 for SSO. As additional protocols are supported, this page will be updated.

SSO integration carries an additional fee, and is included as a standard benefit of the Enterprise and Sustaining Partner plans. Contact the Aviary team to discuss adding it to your subscription.

⁠

How SAML 2.0 authentication works in Aviary

SAML 2.0 (Security Assertion Markup Language) is an open standard that lets an institution’s central login system vouch for a person to an outside application. Two parties participate:

The identity provider (IdP) is the system your institution already operates to authenticate people — Shibboleth, Okta, Microsoft Entra ID, PingFederate, ADFS, or similar. It holds the credentials and performs the actual authentication.

The service provider (SP) is the application the person wants to reach. In this configuration, Aviary is the service provider.

Aviary never receives or stores institutional passwords. Credentials are entered only at your IdP, and Aviary is told the outcome.

The sign-in sequence

A person opens your organization’s Aviary site and selects the SSO login button.

Aviary redirects them to your IdP’s SSO target URL.

Your IdP authenticates them by whatever means it normally uses, including multi-factor authentication if your institution requires it.

Your IdP returns a signed SAML response to Aviary’s callback URL. The response contains an assertion: a statement identifying the person and carrying the attributes your IdP has been configured to release.

Aviary validates the signature against the certificate published in your IdP’s metadata, reads the NameID and attributes from the assertion, and matches them to an Aviary account or creates one.

The person is signed in and receives whatever access their Aviary role and your organization’s permissions allow.

What configuration actually involves

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 SSO does and does not change

SSO governs how people prove who they are. It does not by itself grant them anything in your organization.

Signing in through SSO makes someone a registered user. Registered users can see public content and whatever your organization has opened to logged-in users.

Organization roles — Organization Owner, Organization Admin, Organization User, Assigned User — are still granted deliberately, from the Users page. See Manage Users.

The order of operations differs under SSO: a person must sign in through SSO once before you invite them to the organization. The Manage Users page documents this sequence in full, and it is the most common point of confusion after setup.

You may configure more than one SSO target for a single Aviary site. Each appears as its own option on your login page.

⁠

Before you begin

Gather the following:

Your IdP’s metadata, as either a URL Aviary can reach or an Entity Descriptor XML file you can upload. One or the other is sufficient.

A contact who administers your IdP. You will need them to register Aviary as a service provider and to confirm which attributes they release.

A list of the attributes your IdP releases, if available. Comparing it against Aviary’s defaults up front saves a troubleshooting cycle later.

Recommended: a test account in your IdP

If your institution is able to create a test user account in your IdP and share its credentials with Aviary staff, the configuration process goes considerably faster. This is not required, but it is the single most useful thing an organization can do to shorten setup.

Without a test account, every problem has to be diagnosed indirectly. Aviary describes what it expects, someone at your institution attempts a sign-in and reports what happened, and your IdP administrator interprets the result — a cycle that can take days per issue and consumes the time of the staff who have the least of it to spare. With a test account, Aviary staff can reproduce a failure, read the SAML response, identify the cause, and tell your IdP administrator precisely what needs to change.

aviary@weareavp.com⁠

to arrange this, and disable or delete the account once the configuration is confirmed working.

⁠

Step 1 — Create the authentication configuration

Open Integrations / Authentication Configuration.

⁠

Select Add Configuration. The Create Identity Provider form opens.

⁠

Complete the naming fields:

Field

Required

What to enter

IdP Name

Yes

The label shown in the Aviary interface when someone signs in through this integration. Any label you like — most organizations use the institution or IdP name.

SSO Group Label

Yes

The label that identifies the SSO user group on the login page. It renders as “[SSO Group Label] Users” above the SSO login button, and “Non-[SSO Group Label] Users” above the standard login form. Defaults to the IdP Name if left blank.

⁠

Then provide your IdP’s metadata, using whichever of the two you have:

Field

What to enter

IdP Metadata URL

The metadata URL from your IdP. If the URL is valid, the IdP Metadata Settings below populate automatically when you move the cursor out of the text box.

IdP Metadata XML

The Entity Descriptor XML from your IdP, uploaded as a file. The IdP Metadata Settings populate automatically on upload.

⁠

Step 2 — Review the IdP metadata settings

Aviary fills these in from the metadata you supplied. Expand the IdP Metadata Settings section using the + control to review them, and correct anything that looks wrong before continuing. All of them can be edited by hand if your metadata was incomplete.

Field

What it holds

IdP Entity ID

The unique URI identifying your SAML identity provider. Often the same as the IdP Metadata URL you provided.

SSO Target URL

The redirect URL Aviary sends people to for authentication with your IdP.

IdP Cert

Your IdP’s certificate. Optional, depending on the certificate type your IdP uses. Populated automatically when present in the metadata. If the IdP Cert Multi fields below hold values, this is likely empty.

IdP Cert Fingerprint

The certificate fingerprint. Optional, on the same terms as IdP Cert.

IdP Cert Fingerprint Algorithm

The algorithm used to compute the fingerprint. Optional, on the same terms as IdP Cert.

⁠

IdP Cert Multi

Some IdPs publish separate keys for signing and for encryption rather than a single certificate. When yours does, those keys appear here, read from the metadata.

Field

What it holds

Signing

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

Encryption

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

⁠

You will generally populate either IdP Cert and its fingerprint fields, or the IdP Cert Multi fields — not both. Which applies depends on how your IdP publishes its keys.

A signing key is required. Aviary validates the SAML response against it, so a configuration without one will not authenticate anyone. An encryption key is optional, and may be the same certificate as the signing key — if your IdP publishes a single key that serves both purposes, use that value in both fields.

When the settings are correct, select Create Identity Provider. Aviary returns you to the Authentication Configurations page, where the new configuration appears in the table. It is not enabled yet.

⁠

Step 3 — Send Aviary’s URLs to your identity provider

Your IdP administrator needs two values from Aviary before the integration can work. Both are in the configuration table:

Metadata URL. Select Metadata in the table to load Aviary’s metadata in your browser, then copy the URL from the address bar and send it to your IdP.

Callback URL. Use the copy icon beside the Callback URL in the table, and send that to your IdP as well. This is the endpoint your IdP posts the SAML response to, and some IdPs refer to it as the Assertion Consumer Service (ACS) URL or the reply URL.

⁠

Your IdP administrator will use these to register Aviary as a service provider on their side, and to configure which attributes are released to Aviary.

⁠

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

What to enter

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

Select Enable beside the configuration in the Authentication Configurations table.

Open your 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⁠

If you have not already provided a test account in your IdP, doing so at this point will usually resolve the issue faster than continuing to diagnose it remotely. See Recommended: a test account in your IdP above.