## 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.

- Access Sandbox socure_public_account_id: `https://riskos.sandbox.socure.com/developers/api-keys`.
- Access Production socure_public_account_id: `https://riskos.socure.com/developers/api-keys`.

## Set Up Single Sign-On (SSO) with IBM Security Verify

### 1. Configure SAML in IBM Security Verify

Follow these steps to create a SAML 2.0 integration in IBM Security Verify:

1. Log into your IBM Security Verify account.
2. From the **Applications** section, select **Add an application**.
3. On the **Select Application Type** form, select **Custom Application**.
4. On the **General** tab:
   - **Settings**: Check **Enabled** and **Show on launchpad**.
   - **Descriptions**: Enter a short description for this application.
   - **Company name**: Enter **Socure**.
   - **Theme**: Select **default**.
5. On the **Sign-on** tab:
   - **Sign-on method**: Select **SAML 2.0**.
   - **Provider ID**: Enter one of the following:
     - **Sandbox environment**: `https://riskos.sandbox.socure.com/saml2/socure_public_account_id`
     - **Production environment**: `https://riskos.socure.com/saml2/socure_public_account_id`
   - **Assertion consumer service URL (HTTP - POST)**: Enter `https://api-dashboardv2.socure.com/saml2/SSO`.
   - **Use identity provider initiated single sign-on**: Check.
   - **Target URL**: Leave blank.
   - **Service provider SSO URL**: Leave blank.
   - **SessionNotOnOrAfter**: Enter `7200`.
6. Complete the **Attribute mappings** as follows:

| 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 role(s) a user should have when they access RiskOS™, add a **new custom attribute**:
  - **Data type:** string array
  - **Display Name:** `https://dashboard.socure.com/attributes/role`
  - **Variable Name:** RoleName
  - **Enum:** Checked
  - **Attribute Members:** Flexible display name, value must match valid RiskOS™ system-defined role name.

- The 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 |

### 2. Send the SAML metadata to Socure

After setting up the SAML App integration, download the SAML metadata file and securely share it with Socure. 
Do not copy and paste just the X.509 certificate. Socure requires the full SAML metadata file (XML format) that includes your entity ID, endpoints, and certificates.

> Important: Customers must provide two separate metadata files to Socure:
> - One for the RiskOS™ Sandbox environment
> - One for the RiskOS™ Production environment
> After receiving your SAML metadata file, your Technical Account Manager will confirm SAML is enabled for your account.

### 3. Test the integration

To test the SAML integration, go to the IdP Admin Console, create a user, assign Socure's RiskOS™ app, and role(s) via the custom RoleName SAML attribute. When the user launches the RiskOS™ app from the IdP dashboard:

- 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 not assigned, the system defaults to assigning Analyst role.

### 4. Assign users to RiskOS™

If managing role assignment to users with the custom SAML attribute for RoleName, assign role(s) to the user when assigning the application. 
If a role is not assigned, the system defaults to assigning Analyst role.

> Note: RiskOS™ can have only 1 user assigned as Account Owner. 
> A role assigned to a user applies in both Sandbox and Production. 
> Users must re-authenticate every 12 hours by default; specify a shorter duration using the maxAuthenticationAge parameter for further security hardening.