## Before you begin

You will need your **socure_public_account_id**, available in the RiskOS™ Dashboard on the **Developer Workbench > API Keys** page under the **Customer ID** section.

## Set Up Single Sign-On (SSO) with Google Workspace

### 1. Configure SAML in Google Workspace

Follow these steps to create a SAML 2.0 integration in Google Workspace:

1. Log into your Google Workspace account.
2. From the **Admin Console Home Page**, go to **Apps > Web and mobile apps**.
3. Click **Add App > Add custom SAML app**.
4. On the **App Details** page:
   - Enter the app name as **Socure SSO Integration**.
   - _(Optional)_ Add a description.
   - _(Optional)_ Upload a PNG or GIF file as an app icon. If no icon is uploaded, the system will generate one using the first two letters of the app name.
5. Click **Continue**.

### 2. Configure SAML settings

On the **Google Identity Provider Details** page, enter the following values:

| Property | Value |
| --- | --- |
| **ACS URL** | Enter: `https://api-dashboardv2.socure.com/saml2/SSO` |
| **Entity ID** | Enter one of the following:<br>- **Sandbox environment**: `https://riskos.sandbox.socure.com/saml2/socure_public_account_id`<br>- **Production environment**: `https://riskos.socure.com/saml2/socure_public_account_id` |

### 3. Configure SAML attribute statements

When setting up attribute statements, ensure the following attributes are configured:

| Name | Name Format | Value | Required? |
| --- | --- | --- | --- |
| `urn:oid:2.5.4.42` | Unspecified | `user.firstName` | **Yes** |
| `urn:oid:2.5.4.4` | Unspecified | `user.lastName` | **Yes** |
| `urn:oid:2.5.4.20` | Unspecified | `user.phoneNumber` | **Yes** |
| `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` | Unspecified | `user.email` | **Yes** |
| `https://dashboard.socure.com/attributes/role` | URI Reference | `String.join(",", appuser.RoleName)` | **Optional** |

**If you want to manage what role(s) a user should have when they access RiskOS™**, you will need to add a **new custom attribute**. Fill out the details as follows:
- **Data type:** string array
- **Display Name:** `https://dashboard.socure.com/attributes/role`
- **Variable Name:** RoleName
- **Enum:** Checked
- **Attribute Members:**
  - **Display name** is flexible and can be defined as you prefer, however the **value** has to match a valid RiskOS™ system-defined role name.

The following table lists valid system-defined role names available in RiskOS™:

| Example Display Name | Value |
| --- | --- |
| Admin | administrator |
| Acc Owner | account owner |
| Dev | developer |
| Fraud Analyst | fraud analyst |
| Compliance Analyst | compliance analyst |
| Compliance Officer | compliance officer |
| Compliance Supervisor | compliance supervisor |

### 4. Enable the SAML App in Google Workspace

Once the SAML App integration is created, enable access for users:

1. From the **Admin Console Home Page**, go to **Apps > Web and mobile apps**.
2. Select your **Socure SSO Integration** app.
3. Click **User access**, then select **On for everyone**.
4. Click **Save**.

### 5. Send the SAML Metadata to Socure

After setting up the SAML App integration, click **Download metadata** to download the **SAML metadata file** and securely share it with Socure.

Do not copy and paste just the X.509 certificate from the SAML Setup Instructions page. Socure requires the **full SAML metadata file** (XML format), which includes your entity ID, endpoints, and certificates.

### 6. Test the integration

To test the SAML integration, go to the IdP Admin Console, create a user, assign Socure's RiskOS™ app to the user and assign role(s) via the custom `RoleName` SAML attribute. When the user launches the RiskOS™ app from the IdP dashboard, the following occurs:
- The **Users** tab on the **Users** page in RiskOS™ is populated with the user's name, email address, and phone number.
- The user is assigned the role(s) specified in the RoleName custom SAML attribute. If role(s) is not assigned, the system will default to assigning **Analyst** role to the user.

### 7. Assign users to RiskOS™

If you are planning to manage role assignment to users **and** you have configured the custom SAML attribute for `RoleName`, you can assign role(s) to the user when assigning the application. If a role is not assigned, the system will default to assigning **Analyst** role to the user.

> 📘 Users are required to re-authenticate every 12 hours by default; however, you can specify a shorter duration using the `maxAuthenticationAge` parameter for further security hardening.