Channel Partner

As a Channel Partner, configure a SAML app integration for RiskOS™ Single Sign-On (SSO) with Account Architecture V2.

This guide walks through setting up a SAML app integration for RiskOS™ account on Account Architecture V2 using Okta as an illustrative Identity Provider. You configure the SAML application, map the required SAML attributes, assign users, and retrieve the metadata URL that Socure uses to register your identity provider.

Before you begin

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

SAML endpoints

Field	Purpose	Example value
ACS URL	Endpoint where the IdP posts the SAML response.	`https://user-access-manager-prod.auth.us-east-1.amazoncognito.com/saml2/idpresponse`
Audience Restriction (SP Entity ID)	Identifies the User Pool acting as the SP (must match the SAML audience).	`urn:amazon:cognito:sp:us-east-1_fXpfelaxM`
Default Relay State	Tells Socure which IdP to use and where to redirect after authentication.	`identity_provider=saml-<publicAccountId>-<envId>&client_id=hh218b94fhq1f15k0qgtp9quc&redirect_uri=https://api-dashboardv2.socure.com/saml/SSO&response_type=code&scope=openid` For example, `identity_provider=saml-acc-gU5p9W5wFj-1&client_id=hh218b94fhq1f15k0qgtp9quc&redirect_uri=https://api-dashboardv2.socure.com/saml/SSO&response_type=code&scope=openid`

Default Relay State — parameter breakdown

Parameter	Description
`identity_provider`	SAML identity provider name (`saml-<publicAccountId>-<envId>`) For example `saml-acc-gU5p9W5wFj-1` 1 is for RiskOS™ Production 3 is for RiskOS™ Sandbox
`client_id`	Cognito app client ID. Needs to be the following specific value: `hh218b94fhq1f15k0qgtp9quc`
`redirect_uri`	Dashboard SSO callback endpoint. Needs to be the following specific value: `https://api-dashboardv2.socure.com/saml/SSO`
`response_type`	OAuth response type. Needs to be the following specific value: `code`
`scope`	Requested OAuth scope. Needs to be the following specific value: `openid`

📘
Environment ID:
Use the suffix that matches your environment in the identity_provider value:

1 — Production

3 — Sandbox

SAML attributes

Map the following SAML attributes in your SAML application. Set the Name format to Unspecified for every attribute except https://dashboard.socure.com/attributes/role, which uses URI Reference:

SAML attribute	Application attribute	Description
`accountContext`	`identityProvider`	Account context identifier. Enter it in double quotes. See accountContext format below.
`urn:oid:2.5.4.42`	`user.firstName` or `user.profile.firstName`	First name
`urn:oid:2.5.4.4`	`user.lastName` or `user.profile.lastName`	Last name
`urn:oid:2.5.4.20`	`user.phoneNumber` or `user.profile.mobilePhone`	Phone number
`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`	`user.email` or `user.profile.email`	Email address
`https://dashboard.socure.com/attributes/role`	`String.join(",", appUser.RoleName)`	User roles
`clientScoped`	`clientScoped`	`"true"` or `"false"`. Must be enclosed in double quotes. Assigns users to specific client accounts. Channel partners only; use with `clientAccountIds`.
`clientAccountIds`	`clientAccountIds`	Comma-separated list of one or more public account IDs (for example, `acc-xgd5Fgdtdy` or `acc-fg5FGgdgrrx,acc-xfs67fgrhd`). Channel partners only.

accountContext format

Enter the accountContext as the identityProvider value, enclosed in double quotes:

Single SAML app: "saml-<publicAccountId>-<envId>" — for example, "saml-acc-gU5p9W5wFj-1"
Multiple SAML apps for the same account: append an alias name, "saml-<publicAccountId>-<envId>-<alias-name>" — for example, "saml-acc-gU5p9W5wFj-1-external"

📘
Required and optional attributes:

Required:

accountContext

firstName

lastName

phoneNumber

Optional:

role

clientScoped and clientAccountIds (pass together)

role
Configure the role attribute to control role assignment through SAML:

If specified — Socure assigns the role named in the SAML assertion.

If not specified — Socure defaults to the Fraud Analyst role during Just-In-Time (JIT) creation, the first time the user accesses RiskOS™.

clientScoped and clientAccountIds
These optional attributes must be passed together and are relevant for channel partners.
Channel partners can set up two SAML apps to control access for internal versus external (client) users:

Internal users — need access to all client accounts. Configure the first SAML app without clientScoped and clientAccountIds.

External users — need access to specific client accounts. Configure the second SAML app with clientScoped and clientAccountIds.

Multi-IdP: multiple identity providers per account

A single account can have multiple SAML Identity Providers (for example, separate SAML apps for different teams, regions, or IdP vendors).

Each IdP is distinguished by an alias — 1–6 character lowercase alphanumeric suffix appended to the provider name.

Provider naming

Scenario	Provider Name Format	Example
Single IdP (default)	`saml-<publicAccountId>-<envId>`	`saml-acc-JOOrE07GA2-1`
Multi-IdP (with alias)	`saml-<publicAccountId>-<envId>-<alias>`	`saml-acc-JOOrE07GA2-1-clnt1`

Alias rules:

1–6 characters
Lowercase alphanumeric only (a-z, 0-9)
Must be unique per account + envId combination
Examples: okta1, emea, ping, clnt1

Setup

First IdP — create without alias (backward compatible):

{
  "publicAccountId": "acc-JOOrE07GA2",
  "metadataUrl": "<https://idp-1.example.com/sso/saml/metadata>",
  "envId": 1
}

→ Provider name: saml-acc-JOOrE07GA2-1

Additional IdPs — create with alias:

{
  "publicAccountId": "acc-JOOrE07GA2",
  "metadataUrl": "<https://idp-2.example.com/sso/saml/metadata>",
  "envId": 1,
  "alias": "clnt1"
}

→ Provider name: saml-acc-JOOrE07GA2-1-clnt1

Default Relay State for multi-IdP

Each IdP needs its own relay state with the correct identity_provider value:

IdP	identity_provider
Primary (no alias)	`saml-acc-JOOrE07GA2-1`
Secondary (alias: `clnt1`)	`saml-acc-JOOrE07GA2-1-clnt1`

Role behavior with multiple IdPs

Scenario	Behavior
User logs in via IdP-1 with `role-1`	`role-1` is assigned
Same user logs in via IdP-2 with `role-2`	`role-1` is removed, `role-2` is assigned (replace strategy)
IdP sends no roles / invalid roles	Existing roles are retained (no change)
User is Account Owner and IdP omits Account Owner role	Login is blocked (Account Owner demotion protection)

📘
Microsoft Entra ID - Configuring SAML App for RiskOS Production
If you are using Microsoft Entra ID, EntityID must be different in SAML Metadata XML for RiskOS Sandbox and RiskOS Production.
Entra ID does not allow same EntityID for multiple SAML applications. Make sure the EntityID in the SAML metadata XML for RiskOS Production is different than the entityID in the SAML Metadata XML for RiskOS Sandbox. Socure will not be able to configure SAML for RiskOS Production unless the entityID is different.
See screenshot below that shows the entityID in the SAML metadata XML file.

📘
Microsoft Entra ID - Override Audience Claim Value when configuring SAML app for RiskOS Production
When configuring SAML app for RiskOS Production, update the Audience override from Attributes & Claims -> Advanced SAML claims options -> Edit
Check the box that says "Override audience claim". Update Audience claim value to be:
urn:amazon:cognito:sp:us-east-1_fXpfelaxM

See illustrative example below.

Create an Okta app integration

Step 1 — Create the app integration

In the Okta Admin Console, go to Applications > Applications, click Create App Integration, select SAML 2.0, and click Next.

Configure the SAML integration

Step 1 — General settings

Confirm the App name under General Settings, then continue to the SAML configuration.

Step 2 — Configure SAML settings

Enter the values Socure provides for your environment:

Single sign-on URL — the ACS URL. Keep Use this for Recipient URL and Destination URL selected.
Audience URI (SP Entity ID) — the SP entity ID.
Default RelayState — the relay state string for your account and environment.
Name ID format — Select EmailAddress.

Step 3 — Finish

Complete the feedback step and click Finish.

Add attribute statements

On the application's Sign On settings, add the attribute statements listed in SAML attributes. Map each SAML attribute name to the corresponding Okta user profile attribute.

How to configure role attribute

To manage RiskOS™ roles through SAML, create a custom RoleName attribute on the application profile before you add the role attribute statement:

Go to Directory > Profile Editor and select your application.

Click Add Attribute, then configure the attribute:

Data type — String array
Display name — https://dashboard.socure.com/attributes/role
Variable name — RoleName
Enum — Selected
Attribute members — Add one member for each role you assign. The value must match a valid RiskOS™ role name (see Roles and permissions); the display name is your choice.

Save the attribute. The new RoleName attribute appears in the application's Attributes list.

Ensure Attribute list shows the role attribute after you save it, as shown in the following screenshot.

Add roleName as an expression (Okta Legacy Configuration)

How to configure accountContext attribute

How to configure clientScoped and clientAccountIds attributes

Add expression for clientScoped

Add expression for clientAccountIds

Sample Decoded SAML Assertion (as received by Socure)

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response Destination="https://user-access-manager-dev.auth.us-east-1.amazoncognito.com/saml2/idpresponse" ID="id-60329139073102282801583932823" IssueInstant="2026-07-01T11:27:37.545Z" Version="2.0"
	xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
	xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
		xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.okta.com/exk14qkxh9z8VaWWV698
	</saml2:Issuer>
	<ds:Signature
		xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
		<ds:SignedInfo>
			<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
			<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
			<ds:Reference URI="#id-60329139073102282801583932823">
				<ds:Transforms>
					<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
					<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
						<ec:InclusiveNamespaces PrefixList="xs"
							xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/>
					</ds:Transform>
				</ds:Transforms>
				<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
				<ds:DigestValue>3udT9hC/arsz7afkfwPVsAnEqS5KcaLdFGJ4TH7PpfM=</ds:DigestValue>
			</ds:Reference>
		</ds:SignedInfo>
		<ds:SignatureValue>REDACTED_SIGNATURE_VALUE==</ds:SignatureValue>
		<ds:KeyInfo>
			<ds:X509Data>
				<ds:X509Certificate>MIIDxxxxxxxx...REDACTED_CERTIFICATE...xxxxxxxx==</ds:X509Certificate>
			</ds:X509Data>
		</ds:KeyInfo>
	</ds:Signature>
	<saml2p:Status
		xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
		<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
	</saml2p:Status>
	<saml2:Assertion ID="id98007094508477714852680778" IssueInstant="2026-07-01T11:27:37.545Z" Version="2.0"
		xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
		xmlns:xs="http://www.w3.org/2001/XMLSchema">
		<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
			xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.okta.com/exk14qkxh9z8VaWWV698
		</saml2:Issuer>
		<ds:Signature
			xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
			<ds:SignedInfo>
				<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
				<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
				<ds:Reference URI="#id98007094508477714852680778">
					<ds:Transforms>
						<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
						<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
							<ec:InclusiveNamespaces PrefixList="xs"
								xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/>
							</ds:Transform>
						</ds:Transforms>
						<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
						<ds:DigestValue>kIqZpZBYdSibCBYHq1vbUi6QO4GgY79Q0+nxqZLYGjM=</ds:DigestValue>
					</ds:Reference>
				</ds:SignedInfo>
				<ds:SignatureValue>REDACTED_SIGNATURE_VALUE==</ds:SignatureValue>
				<ds:KeyInfo>
					<ds:X509Data>
						<ds:X509Certificate>MIIDxxxxxxxx...REDACTED_CERTIFICATE...xxxxxxxx==</ds:X509Certificate>
					</ds:X509Data>
				</ds:KeyInfo>
			</ds:Signature>
			<saml2:Subject
				xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
				<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
				<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
					<saml2:SubjectConfirmationData NotOnOrAfter="2026-07-01T11:32:37.545Z" Recipient="https://user-access-manager-dev.auth.us-east-1.amazoncognito.com/saml2/idpresponse"/>
				</saml2:SubjectConfirmation>
			</saml2:Subject>
			<saml2:Conditions NotBefore="2026-07-01T11:22:37.545Z" NotOnOrAfter="2026-07-01T11:32:37.545Z"
				xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
				<saml2:AudienceRestriction>
					<saml2:Audience>urn:amazon:cognito:sp:us-east-1_sSSrar2Dx</saml2:Audience>
				</saml2:AudienceRestriction>
			</saml2:Conditions>
			<saml2:AuthnStatement AuthnInstant="2026-07-01T11:23:59.841Z" SessionIndex="id1782905257374.553763817"
				xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
				<saml2:AuthnContext>
					<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
				</saml2:AuthnContext>
			</saml2:AuthnStatement>
			<saml2:AttributeStatement
				xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
				<saml2:Attribute Name="https://dashboard.socure.com/attributes/role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
					<saml2:AttributeValue
						xmlns:xs="http://www.w3.org/2001/XMLSchema"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Analyst
					</saml2:AttributeValue>
				</saml2:Attribute>
				<saml2:Attribute Name="accountContext" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
					<saml2:AttributeValue
						xmlns:xs="http://www.w3.org/2001/XMLSchema"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">saml-acc-JOOrE07GA2-3
					</saml2:AttributeValue>
				</saml2:Attribute>
				<saml2:Attribute Name="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
					<saml2:AttributeValue
						xmlns:xs="http://www.w3.org/2001/XMLSchema"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">[email protected]
					</saml2:AttributeValue>
				</saml2:Attribute>
				<saml2:Attribute Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
					<saml2:AttributeValue
						xmlns:xs="http://www.w3.org/2001/XMLSchema"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Jane
					</saml2:AttributeValue>
				</saml2:Attribute>
				<saml2:Attribute Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
					<saml2:AttributeValue
						xmlns:xs="http://www.w3.org/2001/XMLSchema"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Doe
					</saml2:AttributeValue>
				</saml2:Attribute>
			</saml2:AttributeStatement>
		</saml2:Assertion>
	</saml2p:Response>

Assign the application to a user

Step 1 — Add a user

In Directory > People, click Add person.

Step 2 — Enter the user details

Enter the user's first name, last name, username, and primary email, then save.

Step 3 — Assign the application to the user

Open the application's Assignments tab, click Assign, and assign the user. Set the RoleName values for the user as needed, then save.

If you are a channel partner and you want to configure a SAML app for external users to have access to their respective client, you can assign users to specific client accounts using clientScoped and clientAccountIds attributes

Step 4 — Confirm the assignment

Confirm that the user appears in the application's Assignments list.

Retrieve the metadata URL

On the application's Sign On tab, copy the Metadata URL from the Metadata details section. Share this URL with Socure to complete the identity provider setup.

SAML configuration checklist

Request your public account ID from Socure Support or your Account Manager

This is a pre-requisite step before you start your SAML configuration.

Set up SAML app for RiskOS™ Sandbox

Set up Okta SAML app (ACS URL, Entity ID) for RiskOS™ Sandbox

Map email attribute (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress → user.profile.email) — required for JIT

Map accountContext attribute with correct account context (as specified for identityProvider in Default Relay State) — required for JIT

Map firstName (urn:oid:2.5.4.42 → user.profile.firstName) — required for JIT

Map lastName (urn:oid:2.5.4.4 → user.profile.lastName) — required for JIT

(Optional) Map role attribute to control roles assigned to user dynamically from your IdP side.

Assign users/groups to the SAML app

Share the metadata URL with Socure to complete the SAML configuration on Socure's side

Set up SAML app for RiskOS™ Production

Set up Okta SAML app (ACS URL, Entity ID) for RiskOS™ Production

Map email attribute (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress → user.profile.email) — required for JIT

Map accountContext attribute with correct account context (as specified for identityProvider in Default Relay State) — required for JIT

Map firstName (urn:oid:2.5.4.42 → user.profile.firstName) — required for JIT

Map lastName (urn:oid:2.5.4.4 → user.profile.lastName) — required for JIT

(Optional) Map role attribute to control roles assigned to user dynamically from your IdP side.

Assign users/groups to the SAML app

Share the metadata URL with Socure to complete the SAML configuration on Socure's side

Additional IdP (if needed)

Create a separate Okta SAML app for the new IdP

Configure ACS URL, Entity ID, and attributes (same as primary)

Set the Default Relay State with the aliased identity_provider name

Test login to verify the correct provider name and roles flow through

Share the metadata URL with Socure to complete the SAML configuration on Socure's side

Socure SAML configuration

After you complete the Okta configuration, share the metadata URL and your public account ID with Socure. Socure registers the identity provider and enables SAML for your account.

Verification

Test login with a new user — verify JIT creates user with correct name, roles, and use cases
Test login with an existing user — verify roles and profile sync correctly

Updated 3 days ago

Did this page help you?