> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect SSO identities to app users

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = href;
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

export const MultiRelatedLinks = ({sections = []}) => {
  if (!sections || sections.length === 0) {
    return null;
  }
  return <div className="space-y-8">
      {sections.map((section, index) => <RelatedLinks key={index} title={section.title} items={section.items} />)}
    </div>;
};

export const RelatedLinks = ({title, items = []}) => {
  const getBadgeClass = badge => {
    if (!badge) return "badge-default";
    const badgeType = badge.toLowerCase().replace(/\s+/g, "-");
    return `badge-${badge === "ガイド" ? "guide" : badgeType}`;
  };
  if (!items || items.length === 0) {
    return null;
  }
  return <div className="my-8">
      {}
      <h3 className="text-sm font-bold uppercase tracking-wider mb-4">{title}</h3>

      {}
      <div className="flex flex-col gap-3">
        {items.map((item, index) => <a key={index} href={item.href} className="py-2 px-3 rounded related_link hover:bg-[#f2f2f2] dark:hover:bg-[#111827] flex items-center gap-3 group no-underline hover:no-underline border-b-0">
            {}
            <span className={`px-2 py-1 rounded-full text-xs font-semibold uppercase tracking-wide flex-shrink-0 ${getBadgeClass(item.badge)}`}>
              {item.badge}
            </span>

            {}
            <span className="text-base">{item.label}</span>
          </a>)}
      </div>
    </div>;
};

Your SSO service will have a unique user record for each person using it within
your company. When accessing a Box application through this SSO service, if
we're creating a Box user for each SSO user, then we need to create an
association between the SSO user and Box user records.

When a user logs in to Box through the SSO service we will first search for the
user by the association. If a Box user record is found we can begin making
calls as that user to Box APIs. If there is no Box user found will then create
a new Box user with the association to the unique SSO user account.

Exploring the top level of a Box <Link href="/reference/resources/user">user object</Link> we can see
the available options for adding the unique identifier from the SSO service
user object into the Box user object to bind the two together.

```json theme={null}
{
  "address": "900 Jefferson Ave, Redwood City, CA 94063",
  "avatar_url": "https://www.box.com/api/avatar/large/181216415",
  "can_see_managed_users": true,
  "created_at": "2012-12-12T10:53:43-08:00",
  "enterprise": { .. },
  "external_app_user_id": "my-user-1234",
  "hostname": "https://example.app.box.com/",
  "id": 11446498,
  "is_exempt_from_device_limits": true,
  "is_exempt_from_login_verification": true,
  "is_external_collab_restricted": true,
  "is_platform_access_only": true,
  "is_sync_enabled": true,
  "job_title": "CEO",
  "language": "en",
  "login": "ceo@example.com",
  "max_upload_size": 2147483648,
  "modified_at": "2012-12-12T10:53:43-08:00",
  "my_tags": [ .. ],
  "name": "Aaron Levie",
  "notification_email": { ... },
  "phone": 6509241374,
  "role": "admin",
  "space_amount": 11345156112,
  "space_used": 1237009912,
  "status": "active",
  "timezone": "Africa/Bujumbura",
  "tracking_codes": [{ .. }],
  "type": "user"
}
```

There are two recommended methods for creating a binding between a unique user
within the SSO service and a Box user, placing the unique SSO user ID within
the Box user `external_app_user_id` field, or using the unique SSO email address
as the login email for the new user.

## Using `external_app_user_id` (recommended method)

The `external_app_user_id` field was designed to hold a string identifier to
associate a Box user record with an external service, such as an SSO provider
user record.

<Warning>
  You can retrieve app users for a specific application only if such app
  users were created by this application.
  If you use one application to search for users
  created by a different one, no data will be returned.
</Warning>

Using the `external_app_user_id` field for associating the unique SSO user
account with a Box user account is the preferred method of connecting the two
accounts over email, for a number of reasons:

* Email association is only viable for <Link href="/platform/user-types/#managed-users">managed users</Link>. <Link href="/platform/user-types/#app-user">App users</Link> are automatically assigned an email address by Box, meaning that you cannot assign the `login` to be the email from the SSO service.
* Emails have to be unique in Box. This means that if your SSO service user signed up for Box using the same email address, which is not within your Box enterprise, then you will not be able to create a user with that email and won't be able to connect to that existing user.
* The `external_app_user_id` field was designed for this purpose.

## Using `login` (alternative method)

Using the `login` field of a user object to create an account association is
viable under a few conditions:

* Only the <Link href="/platform/user-types/#managed-users">managed users</Link> type is being used, not <Link href="/platform/user-types/#app-user">app users</Link>.
* All email addresses and Box account creation requests are managed by your enterprise, meaning that users cannot independently create Box accounts with those email addresses.

<Warning>
  Email addresses used for users in Box, under the `login` field, must be
  unique. Making a request to create a user with an email that already exists
  for another account will result in a `409 Conflict` error, stating that
  `user_login_already_used`
</Warning>

<RelatedLinks
  title="RELATED APIS"
  items={[
{ label: translate("Create user"), href: "/reference/post-users", badge: "POST" }
]}
/>