SAML SSO and SCIM Guide

Documentation Index

Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt

Use this file to discover all available pages before exploring further.

SAML single sign-on lets users authenticate through your identity provider before entering Minerva. SCIM provisioning lets your identity provider create, update, and deactivate Minerva tenant users. Access: Requires the Admin role or above. In the sidebar, go to Administration > Configuration, then open Authentication under Access and authentication. Use this guide when you need to:

• configure a SAML identity provider for Minerva
• choose whether users can sign in with passwords, SSO, or both
• configure SCIM user provisioning from an identity provider
• rotate SAML signing certificates or SCIM bearer tokens
• set up common identity providers such as Okta, Microsoft Entra ID, PingFederate or PingOne, Rippling, and OneLogin

​

Authentication Settings Page

The Authentication page contains four sections:

• Service provider: Minerva values that you copy into the identity provider
• SAML identity provider: identity-provider metadata, certificate status, save, and test controls
• SCIM provisioning: SCIM base URL, bearer token, default role, role mappings, and provisioning controls
• Sign-in mode: password-only, password plus SSO, or SSO-only access

​

Minerva Production Values

Use these Minerva production values when configuring your production identity provider app.

​

Before You Begin

Confirm these items before changing authentication settings:

• you have Admin access in Minerva
• you have admin access in the identity provider
• the users who need Minerva access have email addresses that match their Minerva user emails
• you know which IdP group, role, or entitlement values should map to Minerva Admin, Developer, or Member roles
• you have a pilot user or group ready for testing

​

SAML SSO Setup

SAML setup is a two-way exchange:

1. Copy Minerva service-provider values into the identity provider.
2. Copy identity-provider metadata or manual IdP values back into Minerva.
3. Save the SAML provider in Minerva.
4. Test SSO from Minerva with an assigned admin user.
5. Choose the tenant sign-in mode.

​

Minerva Values To Copy Into The IdP

• Entity ID identifies Minerva as the SAML service provider.
• ACS URL is where the IdP sends the signed SAML response.
• Keep these values unchanged after go-live unless Minerva support directs a rotation.

​

IdP Values To Save In Minerva

• IdP entity ID, sometimes called issuer
• SSO URL, sometimes called login URL or SAML endpoint
• One or more X.509 signing certificates from IdP metadata or certificate export

​

Recommended SAML Setup Sequence

1. Open Administration > Configuration > Authentication in Minerva.
2. Copy the Entity ID and ACS URL from the Service provider section.
3. Create a SAML application in the identity provider and paste those Minerva values into the service-provider fields.
4. Set the SAML subject or NameID to the email address users will use in Minerva.
5. Download IdP metadata, or copy the IdP entity ID, SSO URL, and signing certificate.
6. Paste the metadata into Minerva and parse it, or enter the IdP values manually.
7. Save the SAML provider, assign a test admin user in the IdP, and run Test SSO in Minerva.
8. After a successful test, choose Password + SSO for rollout or SSO only when password sign-in should be blocked.

​

SAML Field Labels You May See

Different IdPs use different labels for the same SAML values.

​

Sign-In Modes

​

Certificate Security And Rotation

Saved IdP signing certificate contents are hidden after upload. Minerva shows certificate metadata such as expiration date and SHA-256 fingerprint so admins can confirm the active certificate without exposing raw certificate material. When rotating a certificate:

1. Add or rotate the signing certificate in the identity provider.
2. Export fresh IdP metadata, or copy the replacement PEM certificate.
3. Paste the fresh metadata or replacement certificate into Minerva.
4. Save the SAML provider.
5. Run Test SSO before the old certificate expires.

​

SCIM Provisioning Setup

SCIM provisioning uses a Minerva SCIM base URL and bearer token. Generate the token in Minerva, store it in the identity provider, and test the connection before enabling broad provisioning. SCIM does not replace SSO. SAML controls sign-in; SCIM controls the user lifecycle. Configure and test both before moving a tenant to SSO only.

​

Recommended SCIM Setup Sequence

1. Open Administration > Configuration > Authentication in Minerva.
2. Copy the SCIM base URL from the SCIM provisioning section.
3. Generate a bearer token and store it in the IdP immediately. The full token is shown only once.
4. Create or open the SCIM provisioning connection in the IdP.
5. Paste the SCIM base URL and bearer token into the IdP, then test the connection.
6. Assign a small pilot group and confirm users are created or updated in Minerva.
7. Configure role mappings when IdP groups, roles, or entitlements should control Minerva Admin, Developer, or Member access.
8. Enable SCIM provisioning in Minerva after the IdP connection and pilot assignment are working.

​

SCIM Field Labels You May See

​

Provisioning Behavior To Review

The IdP should manage:

• users created through app assignment
• name, email, active status, and mapped role updates
• deactivation or suspension when users are removed from scope

Before broad rollout, confirm:

• whether SCIM should disable dashboard-managed invitations
• whether unmatched users should default to Member or a more restrictive role
• whether group names or app roles are stable enough to use as Minerva role mapping values

​

Role Mapping

Minerva supports these tenant roles for provisioned users: Role mapping rules compare the group, role, or entitlement value sent by the IdP with the values configured in Minerva. Keep those values stable and easy to understand, such as Minerva Admins or Minerva Developers. If no role mapping matches a provisioned user, Minerva applies the configured default role.

​

IdP Quick Guides

The same Minerva values work across major identity providers, but each IdP uses different labels and connector templates. Use the quick guide below with your IdP administrator. Configure SAML first, then SCIM. Keep at least one Admin able to sign in before changing the tenant to SSO only.

​

Okta

For SAML:

1. Create or open the Minerva SAML app integration in Applications.
2. Set Single sign-on URL and Recipient URL to the Minerva ACS URL.
3. Set Audience URI / SP Entity ID to the Minerva Entity ID.
4. Use the user email address as the Name ID and assign a test admin user.
5. Copy the Identity Provider metadata into Minerva or download the certificate and enter the IdP issuer and SSO URL manually.

For SCIM:

1. Enable SCIM provisioning for the same app integration when available.
2. Set the SCIM connector base URL to the Minerva SCIM base URL.
3. Use HTTP Header or bearer-token authentication and paste the Minerva bearer token.
4. Enable create, update, and deactivate user actions.
5. Use Group Push or profile attributes when you want Okta values to drive Minerva role mappings.

Notes:

• If the Provisioning tab is not available, your Okta org or app template may need SCIM enabled by Okta.
• Test with a small assigned group before moving the app to SSO only.

​

Microsoft Entra ID

For SAML:

1. Create or open an Enterprise Application, then choose Single sign-on > SAML.
2. Set Identifier (Entity ID) to the Minerva Entity ID.
3. Set Reply URL (Assertion Consumer Service URL) to the Minerva ACS URL.
4. Use user.mail or user.userprincipalname as the user identifier, depending on the email users use in Minerva.
5. Copy the App Federation Metadata URL or download the SAML certificate and enter the issuer, login URL, and certificate in Minerva.

For SCIM:

1. Open Provisioning for the Enterprise Application and choose automatic provisioning.
2. Set Tenant URL to the Minerva SCIM base URL.
3. Set Secret Token to the Minerva bearer token and test the connection.
4. Scope provisioning to assigned users and groups unless your rollout plan says otherwise.
5. Map Entra groups or app roles to the values configured in Minerva role mapping rules.

Notes:

• Entra provisioning runs on a cycle, so successful changes may not appear instantly.
• Keep the same Enterprise Application for SAML and provisioning when your tenant policy allows it.

​

PingFederate or PingOne

For SAML:

1. Create a SAML application or SP connection for Minerva.
2. Set the partner or relying-party entity ID to the Minerva Entity ID.
3. Set the ACS endpoint to the Minerva ACS URL and use an email NameID format.
4. Export the IdP metadata or record the issuer, SSO endpoint, and active signing certificate.
5. Upload metadata in Minerva or enter the IdP values manually, then save and test.

For SCIM:

1. Create an outbound SCIM connection for Minerva when your Ping deployment includes provisioning.
2. Set the SCIM endpoint/base URL to the Minerva SCIM base URL.
3. Use bearer-token authentication with the Minerva SCIM token.
4. Map user email, given name, family name, and active status.
5. Send group, role, or entitlement values when you want Minerva role mappings to apply.

Notes:

• PingFederate deployments vary by adapter and provisioning connector. Use your IdP administrator to confirm the available SCIM connector.
• Export fresh metadata after signing-certificate rotation and update Minerva before the old certificate expires.

​

Rippling

For SAML:

1. Create a custom SAML or SAML and SCIM app for Minerva in Rippling.
2. Set the ACS or Reply URL to the Minerva ACS URL.
3. Set the SP Entity ID or Audience to the Minerva Entity ID.
4. Use employee email as the SAML subject and assign a pilot group.
5. Copy Rippling IdP metadata into Minerva or enter the SSO URL, issuer, and signing certificate manually.

For SCIM:

1. Enable provisioning on the custom app when your Rippling plan supports SCIM.
2. Set the SCIM URL to the Minerva SCIM base URL.
3. Use the generated Minerva bearer token as the SCIM authentication token.
4. Choose the Rippling employee attributes or groups that should control app assignment.
5. Send group or role values that match the Minerva role mapping rules.

Notes:

• Rippling is often driven by employee lifecycle rules. Confirm who should be assigned before enabling broad provisioning.
• If SCIM is not available in your Rippling app setup, keep user creation in Minerva until your IdP administrator enables it.

​

OneLogin

For SAML:

1. Use a SAML custom connector or a SCIM Provisioner with SAML connector for Minerva.
2. Set ACS URL to the Minerva ACS URL.
3. Set Audience or Entity ID to the Minerva Entity ID.
4. Use email as the NameID value and assign the app to a test user or role.
5. Copy the OneLogin issuer, SSO URL, and signing certificate into Minerva.

For SCIM:

1. Use a SCIM v2 connector when you want lifecycle provisioning.
2. Set SCIM Base URL to the Minerva SCIM base URL.
3. Set the authorization header or bearer token value to the Minerva token.
4. Enable user create, update, and deactivate actions.
5. Map role or group values to the same text configured in Minerva role mapping rules.

Notes:

• OneLogin has several SAML and SCIM connector templates. Select the one that supports both SAML sign-in and SCIM provisioning when you want one app.
• Keep SCIM role values simple and stable, because Minerva matches the configured text values exactly after trimming whitespace.

​

Rollout Checklist

Use this checklist before changing production sign-in behavior:

• SAML app is assigned to a pilot admin user or pilot group in the IdP
• Entity ID and ACS URL in the IdP match the values shown in Minerva
• IdP issuer, SSO URL, and signing certificate are saved in Minerva
• Test SSO succeeds in Minerva
• SCIM base URL and bearer token are saved in the IdP
• SCIM connection test succeeds in the IdP
• pilot users are created or updated correctly by SCIM
• role mapping values match the values sent by the IdP
• a rollback path is available before switching to SSO only

​

Common Issues