# Sign-in and External Auth (SSO)

This guide covers the choices and the criteria for deciding **how users and administrators get in**. How long a sign-in lasts and what happens after repeated failures apply even to tenants that do not use SSO, and are covered here too.

## Three ways to sign in

| Method       | How people get in                                         | Where it is decided                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Password** | Email address and password                                | The “Sign-in” screen (self sign-up, password reset)                                                                                                                                                                                                                     |
| **Passkey**  | The device's biometrics or PIN, without typing a password | Each user registers their own. Under “Settings” > “Passkeys” in the chat, users see their own passkeys (when each was registered and last used) and can delete ones they no longer use (admin and auditor accounts can delete them only while signed in with a passkey) |
| **SSO**      | Your identity provider (IdP) authenticates them           | External Auth                                                                                                                                                                                                                                                           |

**When people sign in with SSO, your identity provider does the authentication.** Decide multi-factor authentication and conditional access on the identity provider's side.

## Signing in to the admin console

**Signing in to the admin console with a password asks for an authentication code by email every time.** Unlike the chat, it asks regardless of the device or where you connect from. Signing in with a passkey or SSO does not ask for a code. Administrators who have registered a passkey can enter their email address and click “Continue” to sign in with the passkey.

**How long an admin console sign-in lasts also follows the “Sign-in” screen** ([What you decide on the “Sign-in” screen](#what-you-decide-in-tenant-settings)).

## Connecting SSO

**Create one setting per identity provider under “Sign-in and Access Sources” > “External Auth”.** You go back and forth between this screen and your identity provider's screen in this order.

1. **Decide the display name and IdP type** — the IdP type is OIDC / OAuth2 or SAML 2.0. **The IdP type cannot be changed later**
2. **Register URLs in the identity provider** — once you choose the IdP type, the URLs to register in the identity provider appear under “IdP Configuration Info” on screen (for OIDC, the Redirect URI; for SAML, the ACS URL, the SP metadata URL and so on). They appear even before you save the External Auth setting, so you can copy them and register them in the identity provider first
3. **Enter the identity provider's details** — for OIDC, the Client ID and Client Secret issued by the identity provider and each endpoint (which can be read automatically from the Issuer URL); for SAML, the IdP Entity ID, the SSO URL, the signing certificate and so on
4. **Decide how attributes map to users** — Link By, bringing in organization and job type, and auto-approval

### Settings

The items in each section of the screen. Items not marked “required” can be left empty.

**Basic Settings**

| Item                               | Details                                                                                                                                                                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Enable External Authentication** | Off by default. When on, the sign-in page shows an SSO button for this setting                                                                                                                                                                   |
| **Entry ID** (required)            | The ID that identifies the setting (for example `my-sso`). It starts with a lowercase letter and uses 2–64 lowercase letters, digits, hyphens and underscores. **It can only be entered when creating the setting, and cannot be changed later** |
| **Display Name** (required)        | The name shown on the SSO button on the sign-in page                                                                                                                                                                                             |
| **Icon**                           | The image shown on the SSO button. PNG or JPEG, up to 512KB                                                                                                                                                                                      |
| **Description**                    | A note on what the setting is for                                                                                                                                                                                                                |
| **IdP Type** (required)            | OIDC / OAuth2 or SAML 2.0. Cannot be changed later                                                                                                                                                                                               |

**OIDC/OAuth2 Settings**

| Item                                                                     | Details                                                                                                                                                       |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Issuer URL**                                                           | Enter it and press auto-detect to fill in the three endpoints below from the identity provider's published configuration (`.well-known/openid-configuration`) |
| **Client ID** (required)                                                 | The client ID issued by the identity provider                                                                                                                 |
| **Client Secret** (required)                                             | The client secret issued by the identity provider. **It is not shown after saving.** Enter it only to change it; saving with it empty keeps the current value |
| **Authorization Endpoint, Token Endpoint, Userinfo Endpoint** (required) | The identity provider's authorization, token and user information URLs                                                                                        |
| **Scopes**                                                               | `openid profile email` by default. Separate them with spaces or commas                                                                                        |

**SAML IdP Settings**

| Item                         | Details                                                                                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **IdP Entity ID** (required) | The identity provider's Entity ID                                                                                                                                      |
| **SSO URL** (required)       | The identity provider's single sign-on URL                                                                                                                             |
| **SLO URL**                  | The identity provider's single logout URL                                                                                                                              |
| **Signing Certificate**      | The identity provider's X.509 signing certificate (PEM)                                                                                                                |
| **Metadata URL**             | The identity provider's metadata URL. **Entering it does not fill in the Entity ID, SSO URL or certificate.** Enter the values written in the metadata into each field |

**IdP Configuration Info** (values this screen shows; copy them and register them with your identity provider)

| IdP type      | Values shown                                                                                                            |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| OIDC / OAuth2 | Redirect URI                                                                                                            |
| SAML 2.0      | ACS URL, SP metadata URL (if the identity provider can read metadata, giving it this URL imports the settings), SLO URL |

**User Linking Settings**

| Item                 | Details                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------- |
| **Link By**          | Email (default) or Subject (sub) ([Link By](#link-by))                                    |
| **Auto Create User** | On by default. Users not yet registered are created in this service automatically         |
| **Auto Approve**     | Don't auto-approve, only specified domains, or everyone ([Auto-approval](#auto-approval)) |

### What the sign-in page shows

**When at least one External Auth setting is enabled, an SSO button for each setting (display name and icon) appears below the email field on the sign-in page.** Users choose between signing in with email and password or with an SSO button. With no enabled setting, no buttons appear.

When every setting is disabled, the External Auth list shows “No active federation entries”.

### Link By

What ties a user in the identity provider to a user in this service. Choose **Email** or **Subject (sub)**. The default is Email.

### Bringing in organization and job type

**In “IdP Claim Mapping”, tie the claim names received from the identity provider to this service's “Organization” and “Job Type”** (for example, claim `soshiki` → Organization). Left empty, standard Microsoft Entra ID attributes (such as Department) are looked up.

**When claim values cannot be used as they are, add “IdP Claim Value Rules”.** Each rule is defined by four items.

| Item                 | Details                                                                                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source Claim**     | The name of the claim sent by the identity provider (for example `department`). It cannot be changed later; to change it, delete the rule and create a new one |
| **Source Value**     | The value the rule applies to. It applies only on an exact match (for example “Sales Dept. Section 1”)                                                         |
| **Target Attribute** | The name of the attribute to set (for example `organization` or `job`)                                                                                         |
| **Target Value**     | The value set on the user (for example an organization code)                                                                                                   |

Each rule can be turned on or off.

### Auto Approve

Whether a user created by signing in through the identity provider for the first time is left pending or approved automatically.

| Choice                                             | Behaviour                                                                                                                                               |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Don't auto-approve (an administrator approves)** | The user becomes “Pending” and cannot sign in until an administrator approves them under “Users and Organizations” > “Users”                            |
| **Auto-approve only specified domains**            | Only users whose email address matches exactly after the @ are approved automatically. Subdomains are added separately. Everyone else becomes “Pending” |
| **Auto-approve everyone**                          | Every user coming from this identity provider is approved automatically, whatever the domain                                                            |

**If people outside your company also use the identity provider, do not choose “Auto-approve everyone”.** Use “Auto-approve only specified domains” and limit it to your own domains.

### Signing in with SSO for the first time

**If an account with the same email address (not an SSO one) already exists, the user is asked to confirm who they are.** On the identity verification screen, entering that account's password joins the two.

In these cases the user is turned away instead:

- An account with the same email address exists and the user cannot be confirmed (to prevent account takeover)
- The contracted account limit has been reached and no new account can be created

In both cases, users are told to contact their system administrator.

## Letting people in through SSO only

**When “SSO-only sign-in” under “External Auth” is turned on, users linked to SSO can no longer sign in with ID and password, reset their password, or use passkeys.** If they try to sign in with a password, they see “This account is SSO-only. Please login using SSO”.

**It does not affect users who are not linked to SSO.** They sign in with a password as before.

**The external API for projects has operations that only users signed in with SSO can use** (`403` `sso_required`).

## What you decide on the “Sign-in” screen

**Decide these under “Sign-in and Access Sources” > “Sign-in”, in “Sign-in methods” and “Sign-in duration”.** They apply to every user in the tenant.

| Item                                          | Choices                                                                                                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Self sign-up**                              | When on, users can create their own account from the sign-in page. Turning it off does not stop users signing in with SSO for the first time from being registered |
| **Password reset**                            | When on, users can reset their password from “Forgot password?” on the sign-in page. Turning it off also invalidates verification codes sent before                |
| **Time until login expires without activity** | 15 minutes to 24 hours                                                                                                                                             |
| **Maximum time a login can last**             | 1 to 30 days                                                                                                                                                       |

- Self sign-up and password reset can also be set to “Default (current behavior)”. Both currently behave as on
- The time without activity must not be longer than the maximum time
- When a current value is outside the range that can be set, the screen says so. Left unchanged, the current value keeps working; to change it, use a value within the range
- Conversation share links are decided under “Connections and Usage Scope” > “Feature permissions”, and archiving under “Record Retention and Delivery” > “Export and Legal Hold” > the “Retention and Legal Hold” tab ([Logs and Audit](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/admin/guide/audit-log-guide.md#keeping-and-sharing-conversations))

**The sign-in duration also applies to signing in to the admin console itself.** Set it too short and it will expire in the middle of administrative work.

To stop people signing in with an email address, use “SSO-only sign-in” rather than self sign-up.

## After repeated mistakes

**After several wrong passwords in a row, the account is locked for a while.** It can sign in again once some time has passed.

**To restore it without waiting, press “Unlock” for that user under “Users and Organizations” > “Users”.** They can sign in straight away. The unlock is recorded in the audit log.

## Stopping and restoring users

**Under “Users and Organizations” > “Users”, these operations are available for each user.** Each asks for confirmation.

| Operation                                          | What happens                                                                                                                                                                                                                                                                         | Can it be undone?                                                                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Approve**                                        | A pending user can sign in                                                                                                                                                                                                                                                           | —                                                                                                                                                         |
| **Suspend**                                        | While suspended, the user cannot sign in. Conversations, files and other data are kept. Suspending stops the user's running conversations and personal schedules, stops the patrols and open runs of projects the user owns, and deletes the user's connections to external services | “Resume” lets the user sign in again. The stopped conversations, schedules, patrols and runs, and the deleted connections, are not restored automatically |
| **Revoke approval**                                | The user can no longer sign in and is removed from the contracted number of accounts. Data is kept. As with “Suspend”, running conversations and the rest are stopped and connections are deleted                                                                                    | Approving again lets the user sign in again. What was stopped and the deleted connections are not restored automatically                                  |
| **Delete user**                                    | **Conversations, files, schedules and other data disappear from the screens and the API**                                                                                                                                                                                            | No                                                                                                                                                        |
| **Unlock**                                         | Clears the lock caused by repeated wrong passwords; the user can sign in straight away                                                                                                                                                                                               | —                                                                                                                                                         |
| **Reset Password**                                 | Creates a temporary password and emails it to the user. If the email cannot be sent, the temporary password is shown on screen for you to pass on                                                                                                                                    | —                                                                                                                                                         |
| **Grant / remove system administrator privileges** | Once granted, the person can get into the admin console and set up and manage everything                                                                                                                                                                                             | Can be removed                                                                                                                                            |

**To stop someone only for a while, use “Suspend”.** Only “Delete user” removes the user from the screens and the API and cannot be undone. The differences between suspending, revoking and deleting (whether the user counts toward the number of accounts, the data, and how to restore) are as in the table above. When someone leaves or moves and you want to keep their data while you decide, use “Suspend” too.

- To have the deleted user's archived conversations, per-conversation work notes and per-user settings records deleted as well, contact SoftBank.
- Conversations and projects under legal hold are not deleted even if the user is deleted ([Logs and Audit](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/admin/guide/audit-log-guide.md#legal-hold))
- Projects and agents left without an owner can be moved to another user under “Users and Organizations” > “Ownership handover”. A moved project is paused, and resumes after the new owner has checked it
- These operations are recorded in the audit log

### Restrictions for violations

**“Users and Organizations” > “Restrictions for violations” lists the users and IP addresses whose use is restricted.** It shows when each restriction ends, and “Lift restriction” removes one without waiting.

A restriction by IP address can affect several users who share that IP address.
