> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RightCrowd

> Connect Serval to your gateway-fronted, self-hosted RightCrowd server so workflows can manage cardholders, access cards, and physical access on demand.

## About RightCrowd

[RightCrowd](https://www.rightcrowd.com/) is a physical identity and access management (PIAM) platform covering workforce access, visitor management, and the cardholder and credential lifecycle. The Serval RightCrowd integration (currently in beta, shown with a Beta badge in the integrations catalog) connects to your self-hosted RightCrowd server through its SOAP web services. It is built for deployments where the RightCrowd server sits behind an API gateway, such as Azure API Management secured by Microsoft Entra ID. Once connected, Serval workflows can look up, create, update, suspend, and resume cardholders directly on your RightCrowd server.

**Authentication:** OAuth2 client credentials against the identity provider that secures your API gateway (for example Microsoft Entra ID). Serval stores your Client ID, Client Secret, Token URL, and optional Scopes, exchanges them for an access token at your token endpoint, and attaches it to every outbound call automatically. Direct basic-auth connections to a RightCrowd server are not supported yet.

**Data sync:** On-demand only. There is no scheduled sync, directory import, or resource ingestion - data moves only when a workflow runs a RightCrowd SOAP operation.

## What the RightCrowd integration enables

| Capability                           | Description                                                                                                                                                                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SOAP requests from workflows         | The "RightCrowd ProvisioningService1 SOAP API request" action runs any supported SOAP operation by name and returns the parsed response, plus the raw request and response XML for debugging.                                  |
| Cardholder lifecycle management      | AddCardholder, ModifyCardholder, DeleteCardholder, SuspendCardholder, ResumeCardholder, and ForgetCardholder manage cardholder records, access methods (cards), access levels, and activation dates on your RightCrowd server. |
| Cardholder lookup and search         | GetCardholder, LoadCardholder, and SearchCardholders retrieve cardholder records, including custom data fields (CDFs), access levels, biometrics, and attachments.                                                             |
| Entity categorization                | CategoriseEntity assigns RightCrowd entities to categories.                                                                                                                                                                    |
| Automatic authentication and routing | Serval fetches OAuth2 bearer tokens for you and routes every call to your server's ProvisioningService1 endpoint - no token handling in workflows.                                                                             |

The supported operations are the ten listed above, fixed by the ProvisioningService1 service definition that ships with Serval.

## Get your credentials

RightCrowd's SOAP web services have no public API documentation, and the gateway in front of your server (and its OAuth setup) is owned by your organization. Coordinate with whoever operates the gateway. For the typical setup - Azure API Management secured by Microsoft Entra ID - you create an app registration that Serval uses as its OAuth2 client. See Microsoft's guide to the [OAuth 2.0 client credentials flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow).

<Steps>
  <Step title="Register an app for Serval">
    In the Azure portal, search for and select **App registrations**, then select **New registration** and register a client application for Serval.
  </Step>

  <Step title="Record the Client ID">
    On the app's **Overview** page, record the **Application (client) ID**. This is the **Client ID** field in Serval.
  </Step>

  <Step title="Create a client secret">
    Under **Manage**, select **Certificates and secrets**, create a **New client secret**, and copy its value immediately. This is the **Client Secret** field.
    <Warning>The secret value is only shown once at creation. If you lose it, create a new secret.</Warning>
  </Step>

  <Step title="Build the Token URL">
    Build the token endpoint from your tenant: "[https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token](https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token)", replacing "tenant-id" with your tenant's ID.
  </Step>

  <Step title="Set up scopes and permissions">
    For **Scopes**, use the application ID URI of the gateway's backend app suffixed with "/.default" (for example "api://backend-app-client-id/.default"), and have an admin grant the client app the required application permission on that backend app.
  </Step>

  <Step title="Confirm the base URL with your gateway owner">
    Ask your gateway owner for the base URL that fronts the RightCrowd web services. You will enter only the host and base path in Serval - Serval appends "/RightCrowd/WS/ProvisioningService1.asmx" itself. For gateway-side token validation setup, see [Protect an API in Azure API Management with OAuth 2.0 and Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-protect-backend-with-aad).
  </Step>
</Steps>

<Note>
  Direct connections to a RightCrowd server using basic authentication are not supported yet. The integration requires an OAuth2-capable gateway in front of the server.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the RightCrowd integration">
    Find RightCrowd in the Serval integrations catalog (it carries a Beta badge) and start a new connection. Every field except Scopes is required and marked with an asterisk.
  </Step>

  <Step title="Enter the API Base URL (required)">
    Enter only the host and base path, for example "[https://api.example.com/](https://api.example.com/)". The form describes the field as "Base URL for the RightCrowd API (do not include /RightCrowd/WS/ - just the host and base path)". Leaving it blank shows "This field is required".
    <Warning>Do not include "/RightCrowd/WS/" - Serval appends the web services path automatically. The URL must start with "https\://" or "http\://", or saving fails with an error that includes "API base URL must start with https\:// or http\://".</Warning>
  </Step>

  <Step title="Enter the Client ID (required)">
    Paste the Application (client) ID from your app registration. The form describes it as "OAuth2 Client ID for API access". Leaving it blank shows "This field is required".
  </Step>

  <Step title="Enter the Client Secret (required)">
    Paste the full client secret value into the masked password input. The form does not flag a blank secret inline - if you leave it empty, saving fails with an error that includes "Invalid RightCrowd configuration: client secret is required".
  </Step>

  <Step title="Enter the Token URL (required)">
    Paste your OAuth2 token endpoint, for example "[https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token](https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token)". Leaving it blank shows "This field is required", and it must start with "https\://" or "http\://", or saving fails with an error that includes "token URL must start with https\:// or http\://".
  </Step>

  <Step title="Add Scopes (optional)">
    Add each OAuth scope as a tag, for example "api://client-id/.default". You can paste a comma-separated list and the form will split it. Adding a scope that is already in the list shows a message ending in "is already added". For Entra ID gateways, the ".default" application scope of the gateway's backend app is typically required to get a token the gateway will accept.
  </Step>

  <Step title="Save the connection">
    Save the form. Serval validates only the field formats at save time. If a value is rejected, the error starts with "Failed to install integration" and names the problem, for example "Invalid RightCrowd configuration: API base URL must start with https\:// or http\://".
  </Step>
</Steps>

<Warning>
  When editing this connection later, the Client Secret appears masked with a control to replace it (a pencil icon on the connection settings form, or a Replace button in the configure dialog). Re-enter the complete secret every time you save changes - even if you are only changing another field. Saving without re-entering it is rejected: depending on where you edit, you see a generic "Failed to update configuration" message or an error that includes "client secret is required". Keep the secret somewhere retrievable, or be ready to create a new one in your identity provider whenever you edit the connection.
</Warning>

## Verifying the connection

Saving the connection checks field formats only. Serval does not request a token from your Token URL or call your gateway at save time, and this integration does not ship a built-in connection health check - the first end-to-end proof comes from the first SOAP call.

To verify the connection, run a workflow that uses the "RightCrowd ProvisioningService1 SOAP API request" action - a GetCardholder call makes a good smoke test. A successful response confirms the whole chain end to end: gateway routing, OAuth2 token issuance from your Token URL, and SOAP connectivity to the RightCrowd web services.

<Tip>
  If the first SOAP call fails right after connecting, check **Scopes** first. A token request can succeed with the wrong scope, but an Entra ID-secured gateway typically only accepts tokens that carry its backend app's ".default" application scope. Confirm the scope and the admin-granted application permission with your gateway owner.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Every SOAP call fails after connecting">
    The most common cause is including "/RightCrowd/WS/" in the **API Base URL**. Serval appends "/RightCrowd/WS/ProvisioningService1.asmx" automatically, so entering the full web services path yourself doubles the segment and every call fails. Enter only the host and base path, for example "[https://api.example.com/](https://api.example.com/)".
  </Accordion>

  <Accordion title="Editing the connection requires re-entering the Client Secret">
    The connection form requires the full Client Secret on every save, not just the first one. Use the pencil icon (settings form) or Replace button (configure dialog) on the **Client Secret** field, paste the complete secret value, then save again. Plan for this: keep the secret somewhere retrievable, or be ready to mint a new one, whenever you change any other setting on the connection.
  </Accordion>

  <Accordion title="Token is issued but the gateway rejects requests">
    This integration is built for gateway-fronted deployments (for example Azure API Management with Microsoft Entra ID). The gateway typically only accepts tokens that carry its backend app's ".default" application scope and an admin-granted application permission. Direct connections to a RightCrowd server using basic authentication are not supported yet.
  </Accordion>

  <Accordion title="RightCrowd is SOAP only and operation names are case-sensitive">
    There is no generic REST request action for RightCrowd. Workflows must use the "RightCrowd ProvisioningService1 SOAP API request" action, and operation names must match the service definition's casing exactly (GetCardholder works, getCardholder does not). Available operations: AddCardholder, ModifyCardholder, DeleteCardholder, SuspendCardholder, ResumeCardholder, ForgetCardholder, GetCardholder, LoadCardholder, SearchCardholders, and CategoriseEntity.
  </Accordion>

  <Accordion title="Changing the API Base URL changes the connection's identity">
    The connection's identity in Serval is derived from the host and path of the **API Base URL**. Pointing an existing connection at a different base URL re-keys it as a different connection instance, so treat a base URL change like setting up a new connection.
  </Accordion>

  <Accordion title="http:// is accepted but discouraged">
    Both the API Base URL and Token URL accept "https\://" or "http\://". Use "https\://" in production - your credentials and tokens transit these URLs.
  </Accordion>

  <Accordion title="Beta integration">
    RightCrowd is currently in beta and appears with a Beta badge in the integrations catalog. Behavior may evolve; report issues to support.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your RightCrowd integration.