# SAML single sign-on

import { Aside } from '@astrojs/starlight/components';

SAML single sign-on (SSO) lets your team access Avrea through your existing
identity provider (IdP). Members use the same company sign-in and security
policies they use for other business applications, while administrators manage
access from one place.

With SAML SSO, you can:

- Give members a familiar company sign-in experience.
- Apply your IdP's MFA, conditional-access, and session policies to Avrea.
- Automatically create Avrea memberships after a successful first sign-in.
- Assign a safe default role to new members.
- Require SSO for your verified company domains.

Avrea works with SAML 2.0 identity providers that can export IdP metadata and
send signed assertions. SAML SSO is available with Avrea Enterprise; see
[avrea.com/pricing](https://avrea.com/pricing) for plan details.

## Before you begin

You need:

- An **Admin** role in your Avrea organization.
- Permission to add a SAML application in your identity provider.
- Permission to publish a DNS TXT record for your company domain.
- Your IdP metadata XML.

Your organization slug is the value after `/org/` in the Avrea console URL.
For example, the slug in `https://console.avrea.com/org/acme` is `acme`.

## 1. Add Avrea to your identity provider

Create a SAML application in your IdP and import Avrea's service-provider (SP)
metadata:

```text
https://api.avrea.com/saml/<organization-slug>/metadata
```

Replace `<organization-slug>` with your slug. The metadata supplies the
correct entity ID, assertion consumer service (ACS) URL, signing certificate,
and single logout URL, so importing it is preferable to entering those values
manually.

Configure the IdP to include:

- A **NameID** that uniquely identifies the member.
- A required email attribute containing the member's company email address.
- Optional first-name and last-name attributes.
- A signed SAML assertion.

The asserted email domain must be one of the verified company domains in your
Avrea organization.

## 2. Connect the IdP in Avrea

1. In the [Avrea console](https://console.avrea.com), open your organization.
2. Go to **Settings** → **SSO / SAML**.
3. Paste your IdP metadata into **IdP metadata XML**.
4. Enter the exact attribute names your IdP uses for email, first name, and
   last name. Email is required; the name fields are optional.
5. Choose the **Default role for new members**. **User** is recommended for
   least-privilege access; you can promote individual members later.
6. Choose whether to enable automatic provisioning and IdP-initiated sign-in.
7. Click **Save**.

| Option | What it does |
|---|---|
| **Provision new members automatically** | Creates an Avrea membership on a member's first successful SAML sign-in and assigns the selected default role. |
| **Allow IdP-initiated login** | Lets members launch Avrea directly from an IdP application tile. Leave this off if members should always begin at Avrea. |

<Aside type="note" title="Updating the connection">
Paste the current IdP metadata again whenever you change the attribute mapping
or sign-in options. Upload fresh metadata before an IdP signing-certificate or
SSO endpoint change takes effect.
</Aside>

## 3. Test sign-in

Click **Test connection** after saving. Avrea starts a real sign-in at your IdP
and then shows the NameID, mapped email, mapped name, and received attributes.
The test does not create a member or start an Avrea session.

Check that:

- The mapped email is the member's expected company address.
- The first and last names are mapped correctly, if configured.
- The company domain appears as **Verified** under **Company domains**.

If a domain is **Pending**, publish the TXT record shown in the console, wait
for DNS to update, and click **Verify**.

## 4. Verify a company domain

An organization admin can verify any company domain they control, even when it
does not match their GitHub or Avrea account email:

1. Under **Company domains**, enter the domain and click **Add domain**.
2. Publish the displayed TXT record in the domain's DNS configuration.
3. Click **Verify**. If the record has not propagated yet, wait and click
   **Verify** again to perform a fresh lookup.

The claim remains pending and cannot be used for SAML sign-in or SSO
enforcement until Avrea finds the exact TXT value.

## 5. Roll out SSO

Share Avrea's SSO sign-in flow with your team:

1. Go to [console.avrea.com](https://console.avrea.com).
2. Click **Sign in with single sign-on (SSO)**.
3. Enter a company email address and click **Continue with SSO**.

If IdP-initiated login is enabled, members can also start from the Avrea tile in
your IdP.

Members created through SAML who have not connected GitHub will be prompted to
do so. Connecting GitHub gives them repository and SSH access while SAML
remains their company sign-in method.

## 6. Enforce SSO

After testing with at least one member, you can require SAML for your verified
company domains:

1. Confirm the SAML connection is saved and working.
2. Confirm at least one company domain is **Verified**.
3. Under **Enforce SSO**, enable **Require SSO for verified domains**.

Once enforcement is enabled, members whose verified email addresses match
those domains must use company SSO. Direct GitHub or Google sign-in is blocked
for those members, which keeps authentication policy under your organization's
control.

<Aside type="caution" title="Test before enforcing">
Complete the full sign-in flow with a non-production test member before you
enable enforcement. Keep an active admin session open while you verify the
rollout.
</Aside>

## Troubleshooting

### The metadata cannot be saved

Export fresh SAML metadata from the IdP. It must include the IdP entity ID,
single sign-on URL, and an assertion-signing certificate.

### The test does not show an email

Check that the **Email attribute** in Avrea exactly matches the attribute name
sent by the IdP, including capitalization.

### A member cannot sign in

Confirm that the assertion is signed, the email attribute is present, and its
domain is verified for the organization. If automatic provisioning is off,
only members who have previously used this SAML connection can sign in through
it.

For help with a rollout, contact [support@avrea.com](mailto:support@avrea.com).