> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/integrations/integration-fundamentals/identity-integrations.md). # Identity Integrations ## Overview Integrate with your preferred identity providers to * Verify end-user credentials * Sync information * Receive security alerts * Enable end users to unlock redacted or locked content {% hint style="warning" %} Identity integrations don't control admin access to your Material instance. For admin sign-in, use [Admin SSO](/administration/security/admin-sso.md). {% endhint %}
## Add an Identity Integration 1. From the top bar, click **Integrations** (the puzzle icon). 2. Click **Create Integration.** 3. Click your preferred tool. 4. Click **Create New Integration**. 5. At the top of the form, enter a name for the integration. :warning:The **Save** button remains inactive until after you name the integration. 6. Follow the [Tool Specific Instructions](#tool-specific-instructions) below to complete the required fields. For **Okta SSF**, see the [Okta SSF instructions](/integrations/integration-fundamentals/identity-integrations/okta-ssf.md). For **SAML Identity**, see the [SAML Identity instructions](#saml-identity). ## Tool Specific Instructions
Duo Auth {% hint style="warning" %} Always consult Duo's documentation directly for up-to-date instructions. {% endhint %} **In Duo**: Connect Material to Duo using [Duo's Auth API](https://duo.com/docs/authapi): 1. Log in to the [Duo Admin Panel](https://admin.duosecurity.com/login?next=%2F) and navigate to **Applications**. 2. Click **Protect an Application** and locate **Auth API** in the applications list. 3. Click **Protect this Application** to get your **integration key**, **secret key**, and **API hostname**. 4. Paste these values in Material then **Save**.
OneLogin {% hint style="warning" %} Always consult OneLogin's documentation directly for up-to-date instructions. {% endhint %} **In OneLogin:** Connect Material to OneLogin using the [OneLogin API](https://developers.onelogin.com/api-docs/1/getting-started/dev-overview): 1. [Login](https://app.onelogin.com/login) to OneLogin as an account owner or administrator. 2. Select **API Credentials** from the **Developers** menu. 3. On the API Access page, click **New Credential**. 4. Name your credential (e.g. "Material"), select the **Manage Users** role and click **Save**. Make note of the **client secret** and **client ID**. 5. Paste these values in Material then **Save**.
Okta Token
**Create an Okta Admin** {% hint style="warning" %} Always consult Okta's documentation directly for up-to-date instructions. {% endhint %} 1. In Okta, create a new Okta admin (e.g. "Material Admin") and assign the required roles based on selected capabilities. 1. **Groups** - Group, Help Desk, App, or Read Only Admin 2. **MFA Status** - App or Read Only Admin 3. **End-User Verification** - Help Desk Admin Log in to your Okta organization as the new admin. 2. From the **Security** menu, select API then select **Tokens**. 3. Click **Create Token**. 4. Name your token (e.g. "Material") and click **Create Token**. 5. Copy your API token because you will only see it one time. Paste it into Material. **Create an IP Zone** 1. Navigate to **Security** > **Networks** then click **Add Zone** to create a new **IP Zone**. 2. Name the zone and paste the **Outbound IPs** from Material into the **Trusted Proxy IPs** field. This lets Okta display the correct geographic location during identity verification. 3. Click **Save** in Okta to save the IP Zone.
### SAML Identity The **SAML Identity** integration verifies end users with your identity provider when they open a redacted or locked message. Use it with any provider that supports SAML 2.0. You'll copy values in both directions. Material gives you two values to paste into your identity provider: * `SSO Url`, the endpoint your provider sends the assertion to. Some providers call this the ACS URL or the reply URL. * `Entity ID`, the identifier for Material as the service provider. Your provider gives you back an XML metadata file, which you paste into **Identity Provider (IDP) XML Metadata** in Material. Keep both tabs open while you work. {% hint style="warning" %} This integration verifies end users. It doesn't control admin sign-in to Material, which is configured separately in [Admin SSO](/administration/security/admin-sso.md). {% endhint %}
SAML Identity: Google Workspace {% hint style="warning" %} Always consult Google's documentation directly for up-to-date instructions. {% endhint %} 1. In Material, open the **SAML Identity** integration so the `SSO Url` and `Entity ID` values are visible. 2. In the Google Admin console, click **Apps** > **Web and mobile apps**, then click **Add App** > **Add custom SAML app**. 3. Name the app "Material End-user Verification", then click **Continue**. 4. On the **Google Identity Provider details** page, download the IdP metadata, then click **Continue**. 5. Enter the **Service Provider Details**: 1. `ACS URL`: the `SSO Url` value from Material 2. `Entity ID`: the `Entity ID` value from Material 3. `Name ID format`: **EMAIL** 6. Click **Continue**. 7. Leave the attribute mappings empty, then click **Finish**. Google opens the page for the app you created. 8. Click **View details** below **User access**, set the service status to **On for everyone**, then click **Save**. 9. Back in Material, paste the contents of the metadata file you downloaded into **Identity Provider (IDP) XML Metadata**. 10. Turn on the integration, then click **Save**.
SAML Identity: Microsoft 365 {% hint style="warning" %} Always consult Microsoft's documentation directly for up-to-date instructions. {% endhint %} Configure the integration in Microsoft Entra ID (previously Azure Active Directory). {% hint style="warning" %} Microsoft enforces a minimum session length of one hour. Once someone verifies, they won't be asked to verify again on another protected message until that session expires. {% endhint %} 1. In Material, open the **SAML Identity** integration so the `SSO Url` and `Entity ID` values are visible. 2. In the [Microsoft Entra admin center](https://entra.microsoft.com), click **Entra ID** > **Enterprise apps** > **All applications**. 3. Click **New application** > **Create your own application**. 4. Name the app "Material End-user Verification", select **Integrate any other application you don't find in the gallery (Non-gallery)**, then click **Create**. Microsoft Entra ID opens the page for the app you created. 5. Under **Manage**, click **Properties**, set **Visible to users?** to **No**, then click **Save**. 6. Under **Manage**, click **Single sign-on**, then click **SAML**. 7. Next to **Basic SAML Configuration**, click **Edit** and enter: 1. `Identifier (Entity ID)`: the `Entity ID` value from Material 2. `Reply URL (Assertion Consumer Service URL)`: the `SSO Url` value from Material 8. Click **Save**. 9. Next to **Attributes & Claims**, click **Edit**, then change the source attribute for `Unique User Identifier (Name ID)` from `user.userprincipalname` to `user.mail`. 10. Click **Save**. 11. Return to the **Single sign-on** page. Under **SAML Certificates**, download the **Federation Metadata XML**. 12. Under **Manage**, click **Users and groups**, then assign the app to the users and groups who need it. 13. Back in Material, paste the contents of the Federation Metadata XML file into **Identity Provider (IDP) XML Metadata**. 14. Turn on the integration, then click **Save**. **Optional: ask for verification on every request** Use a [Conditional Access policy](https://learn.microsoft.com/en-us/entra/identity/conditional-access/concept-conditional-access-policies) to require multi-factor authentication on every verification request. 1. From the page for the app you created, under **Security**, click **Conditional Access**, then click **New policy** > **Create new policy**. 2. Enter the policy details: 1. `Name`: Material Security End-user Verification Policy 2. `Users and Groups`: include all users 3. `Grant`: click **Grant access**, select **Require multifactor authentication**, then click **Select**. 4. `Session`: turn on **Sign-in frequency**, set it to 1 hour, then click **Select**. 3. Set **Enable policy** to **On**. 4. Click **Create**.
SAML Identity: Okta {% hint style="warning" %} Always consult Okta's documentation directly for up-to-date instructions. {% endhint %} 1. In Material, open the **SAML Identity** integration so the `SSO Url` and `Entity ID` values are visible. 2. In the Okta Admin Console, click **Applications** > **Applications**, then click **Create App Integration**. 3. Select **SAML 2.0**, then click **Next**. 4. Name the app "Material End-user Verification", select **Do not display application icon to users**, then click **Next**. 5. Under **SAML Settings**, enter: 1. `Single sign on URL`: the `SSO Url` value from Material 2. `Audience URI`: the `Entity ID` value from Material 6. Click **Next**. 7. Select **I'm an Okta customer adding an internal app**, then click **Finish**. 8. Click the **Sign On** tab, then next to **SAML Signing Certificates**, click **View SAML setup instructions**. 9. Copy the IdP metadata at the bottom of the page. 10. Back in Material, paste the metadata into **Identity Provider (IDP) XML Metadata**. 11. Turn on the integration, then click **Save**. 12. In Okta, open the app, click the **Assignments** tab, then assign the app to the users and groups who need it. **Optional: ask for verification on every request** For Okta Classic: 1. From the app, click the **Sign On** tab. 2. Below **Sign On Policy**, click **Add Rule**. 3. Name the rule "Material Security End-user Verification Policy". 4. Below **Access**, check **Prompt for factor**, then select **Every sign on**. 5. Click **Save**. For the Okta Identity Engine, use Okta's application-specific MFA sessions: 1. Click **Security** > **Authentication Policies**, then click **Add a policy**. 2. Name the policy "Material Security End-user Verification Policy", then click **Add rule**. 3. Name the rule "Material Security End-user Verification Rule". 4. At the bottom of the window, below **Re-authentication frequency**, set: 1. **AND Password re-authentication frequency is**: select **Never re-authenticate if the session is active** 2. **AND Re-authentication frequency for all other factors is**: select **Re-authenticate after**, then choose how long to allow between prompts 5. Click **Save**. 6. Click the **Applications** tab, click **Add app**, then click **Add** next to the app you created.
## Troubleshooting #### The **Save** button is inactive in the integration * Confirm you named the integration first. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.material.security/integrations/integration-fundamentals/identity-integrations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.