> For the complete documentation index, see [llms.txt](https://help.sdocs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sdocs.com/s-sign/advanced-signer-scenarios/signer-authentication/cac-piv-verification.md).

# CAC/PIV Verification

This guide outlines how to configure CAC (Common Access Card) and PIV (Personal Identity Verification) authentication for S-Sign using Okta as the Identity Provider.

### The Signer Experience

When a signer receives a document link with CAC/PIV enabled, the workflow will include the SSO:

1. Click Link: The signer clicks the link in their email.
2. Redirect: S-Sign automatically redirects the browser to the Okta login page.
3. Certificate Challenge: The signer inserts their CAC/PIV card and enters their PIN. Okta validates the certificate against the trusted CA.
4. Verification: Upon success, Okta redirects the signer back to the S-Sign document.
5. Access: The document is unlocked, and the signer can proceed to sign.

### Security and Compliance Benefits&#x20;

* Multi-Factor Authentication (MFA): Satisfies federal requirements for hardware-based MFA.
* Non-Repudiation: Digital certificates provide stronger proof of identity than standard email access.
* Audit Trail: The S-Sign Audit Trail will record that the user was authenticated via an external Identity Provider (Okta), including the successful authentication timestamp.

***

### **Prerequisites** <a href="#prerequisites" id="prerequisites"></a>

* **Compatible S-Doc/ S-Sign version**
  * Your Salesforce org must already have S-Doc/ S-Sign version [Fall '25 Release](https://sdoc.atlassian.net/wiki/spaces/SDREL/pages/2477817886) or later to support Okta-based CAC/PIV authentication
* **Add** the `SSign.AuthenticationRedirect` Visualforce Page to the org’s S-Sign configuration:\
  [S-Sign Quick Install & Config Guide – Salesforce Lightning Experience – S-Docs Knowledge Base](https://kb.sdocs.com/knowledge-base/ssign/install-configure-ssign/s-sign-quick-install-salesforce-lightning-experience/#step-2-create-a-salesforce-site)
* **Okta Integration Configured:** If you do not have an Okta account, navigate to the URL below and click ‘**Sign Up**’, then create an Integrator Free Plan:\
  [Okta Integrator Free Plan org configurations | Okta Developer](https://developer.okta.com/docs/reference/org-defaults/)

### Follow the steps below, alternatively watch [Storylane](https://sdocs.storylane.io/share/ectfd5dhtrl4). <a href="#follow-the-steps-below-alternatively-watch-storylane" id="follow-the-steps-below-alternatively-watch-storylane"></a>

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2FVR1k29TEUCSsemTQUHVD%2FScreenshot%202026-10-09%20at%209.41.12%E2%80%AFAM.png?alt=media&amp;token=d9ab7edd-8b5b-4e43-8ba5-9446137fc3aa" alt=""><figcaption></figcaption></figure>

### **Step 1: Quick Configuration for Open ID Connect (Okta)** <a href="#step-1-quick-configuration-for-open-id-connect-okta" id="step-1-quick-configuration-for-open-id-connect-okta"></a>

1. **Log in to Okta:** Access your Okta administrator dashboard
2. **Navigate to Applications:** Go to the **Applications** tab
3. **Create a new app integration:** Click **Create App Integration**
4. **Select OIDC sign-in method:** Choose **OIDC - OpenID Connect** and click **Next**
5. **Choose application type:** Select **Web Application** (or your specific application type) and click **Next**
6. Under **Grant Types**: Ensure **‘Authorization Code’** and ‘**Refresh Token’** are selected
7. Click ‘Advance’ and select the following checkboxes:
   1. **Implicit (hybrid)**
      * Allow ID Token with implicit grant type
      * Allow Access Token with implicit grant type
8. **Configure general settings:**
   * Give the app integration a name
   * Enter your **Sign-in redirect URIs**, which is the URL where Okta will redirect the user after authentication (You will have two URLs, your Salesforce domain and S-Sign Site).
     * First is your internal org, which will include the ssign namespace. Remove sandbox portions for production environment:
     * `https://https://[domainname][--sandboxname]--ssign[.sandbox].vf.force.com/apex/SSIGN__AuthenticationRedirect`
     * Then your S-Sign Site; be sure to add the site’s custom path URL if using:
     * `https://[YourSSignSiteBaseURL][/custompathURL]/apex/SSIGN__AuthenticationRedirect`
   * Example:
     * `https://sdqasandbox--mtest--ssign.sandbox.vf.force.com/apex/ssign__AuthenticationRedirect`
     * `https://sdqasandbox--mtest.sandbox.my.salesforce-sites.com/ssign/apex/SSIGN__AuthenticationRedirect`
   * Enter your **Sign-out redirect URIs** (optional)
9. **Save the integration:** Click **Save**

#### **Configure Claim Attributes for the Integration:** <a href="#configure-claim-attributes-for-the-integration" id="configure-claim-attributes-for-the-integration"></a>

1. In the **Okta Admin Console** interface, **navigate to Security → API.**
   1. Either **Add Authorization Server** (be sure to include your intended signer Audience) or select a previously configured Server.
2. Click the **Claims** tab
3. Click **Add Claim (You will create a new claim entry for each of 3 items below)**
4. Include the following attributes using [**Okta Expression Language**](https://developer.okta.com/docs/reference/okta-expression-language/):

| **Name**                                                                                                                                 | **Value**                                             | **Scopes** | **Type** | **Included** |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------- | -------- | ------------ |
| <p><strong>sub</strong></p><p><em><strong>Note: this claim is the “subject identifier” and is added by Okta by default</strong></em></p> | *(appuser != null) ? appuser.userName : app.clientId* | Any        | access   | Always       |
| **serial\_number**                                                                                                                       | *appuser.serialNumber*                                | Any        | id       | Always       |
| **full\_name**                                                                                                                           | *appuser.cacName*                                     | Any        | id       | Always       |

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2FfHUqgCrNTcjPUEhaVy1t%2Fimage.png?alt=media&amp;token=35bc0f32-9cf9-42f6-919d-bb09118a3f83" alt=""><figcaption></figcaption></figure>

*Fully configured Claim for S-Sign compatibility with Okta Open ID Connect*

5. Under **Access Polices** click ‘Add New Access policy\
   \- Name: *(User-defined)*\
   \- Description: (User-defined)\
   \- Assign to: (leave default selected)
6. Then under the configured **Access Polices**, click **Add Rule**:\
   Under Grant type select:

   \- Device Authorization\
   \- Implicit (hybrid)\
   \- Leave all other default settings selected and save

**Additional Okta Resources:**

1. [***Create OpenID Connect app integrations***](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)
2. [***How to Add Custom Attributes of User Profile as Claims in Tokens***](https://support.okta.com/help/s/article/How-to-add-custom-attributes-of-user-profile-as-claims-in-token?language=en_US)
3. [***Okta Expression Language overview***](https://developer.okta.com/docs/reference/okta-expression-language/)

### **Step 2: Create Alternative Authentication Configuration Record in Salesforce**

1. In Salesforce Setup, go to:\
   `Setup → Custom Metadata Types → Alternative Authentication Configuration → Manage Records`
2. Click **New** to create a new record.
3. Fill in the following:

| Field                       | Value                                                                                                                       | Where to Find in Okta                                                           |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Label**                   | A descriptive name for this configuration                                                                                   | *(User-defined)*                                                                |
| **API Name**                | Auto-generated or customized                                                                                                | *(User-defined)*                                                                |
| **Base\_URL\_\_c**          | Base URL of the Okta authentication page *(e.g.,* `https://site.okta.com`*)*                                                | Okta Admin Console → **Security → API→ Auth Server → \[Server Name] → Issuer**  |
| **Authorize\_URL\_\_c**     | Authorization endpoint path *format (e.g., modify the URL with Auth. Server name* `oauth2/xxxxxxx0xxxxx987/v1/authorize`*)* | Okta Admin Console → **Security → API → Auth. Server → \[Server Name]**         |
| **Client\_Id\_\_c**         | Client ID of the authentication app                                                                                         | Okta Admin Console → **Applications → \[Your Auth App]**                        |
| **Scope\_\_c**              | Scope used for authentication requests (e.g. profile email openid)                                                          | Okta Admin Console → **Security → API → Auth Server → \[Server Name] → Scopes** |
| **Custom\_Parameters\_\_c** | JSON map of required key/value pairs                                                                                        | Keys listed below; values can be customized in Okta                             |

#### **Required Custom Parameters** <a href="#required-custom-parameters" id="required-custom-parameters"></a>

In the **Custom\_Parameters\_\_c** field, enter a JSON object containing the following **keys** (values can be customized in Okta **with the exception of CAC/PIV for type**, but keys must match exactly for S-Docs compatibility):

| **Key** *(required as specified)* | **Value**                              |
| --------------------------------- | -------------------------------------- |
| **type**                          | **CAC/PIV**                            |
| **idNumberLabel**                 | *(User-defined; e.g.: serial\_number)* |
| **fullNameLabel**                 | *(User-defined;* e.g.: full\_name)     |

`{"type": "CAC/PIV","idNumberLabel":"serial_number","fullNameLabel": "full_name"}`

**Optional Custom Parameters**

Adding `"debug": "true"` to your JSON map will add a Visualforce page to the signing process that displays the User’s ID Token Payload. This can aid in investigation during implementation.

#### **Save and Verify** <a href="#save-and-verify" id="save-and-verify"></a>

* Click **Save** in Salesforce.

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2FzkRFnVEffBXccrVCy1fk%2Fimage.png?alt=media&amp;token=b56cd751-10b0-4ebb-bc56-c0bad5fc1a98" alt=""><figcaption></figcaption></figure>

*Example of a complete Alternative Authentication Configuration Detail*<br>

### **Now you can configure your templates for CAC/PIV!**

* **Open your S-Sign enabled S-Docs Template**
* **Assign Signer Profiles** and configure which profiles require CAC/PIV authentication.

  <figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2FUChg017IHAdT2hvspVqJ%2Fimage.png?alt=media&amp;token=47735f31-f4d2-4a41-a907-05c852e9164c" alt=""><figcaption></figcaption></figure>
* For any profiles not needing authentication, simply bypass it at the profile level.

#### Pull in Okta Data to a Stamp Signature <a href="#pull-in-okta-data-to-a-stamp-signature" id="pull-in-okta-data-to-a-stamp-signature"></a>

Signer Profiles with the new Alternative Authentication method assigned gain the new Input Field Type option “Digital Stamp”

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2F4vImL8ELRuCVI5slDonM%2Fimage.png?alt=media&amp;token=f7ba93ad-ae87-4547-bfad-3428bd3da4e8" alt=""><figcaption></figcaption></figure>

This field type will pull the signer’s *full\_name* and *serial\_number* from Okta into a digital stamp:

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2FwBXzIFgO4yL3ViTWTpDg%2Fimage.png?alt=media&amp;token=31349149-9d66-4a37-9fad-b00eb28762fc" alt=""><figcaption><p>Standard Stamp</p></figcaption></figure>

The "Stamp Style" option now includes both "Standard" and "Compact" styles to choose from.

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2F5a5NZP6Eosmv3y6rcCa6%2FScreenshot%202026-11-03%20125406.png?alt=media&amp;token=b832b374-d106-44f0-b5e4-7da8baa762cb" alt=""><figcaption><p>Compact Stamp</p></figcaption></figure>

### Troubleshooting: <a href="#troubleshooting" id="troubleshooting"></a>

| **Error**                                                                                                                                         | **Resolution**                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bad Request 400: Error: Your request resulted in an error. The 'redirect\_uri' parameter must be a Login redirect URI in the client app settings: | <p>Ensure you’ve added redirect URI in your app and have ‘apex/ssign\_\_AuthenticationRedirect’</p><p>appended to the end.</p>                                                                            |
| <h4 id="error-the-authorization-server-id-is-invalid"><code>Error: The authorization server id is invalid.</code></h4>                            | <p>In Salesforce, ensure Setup → Custom Metadata Types → Alternative Authentication Configuration → Manage > Authorize URL matches the API server URL (In okta > security > API> Server Used)</p><p> </p> |

**Debugging**

Adding `"debug": "true"` to your JSON map will add a Visualforce page to the signing process that displays the User’s ID Token Payload. This can aid in investigation during implementation.

<figure><img src="https://2828008455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG8JG5qkkPJ4Es3cSKC5u%2Fuploads%2FFMBuJNtr0fvWknezNFln%2Fimage.png?alt=media&amp;token=0ab3c22d-a5f1-438a-8c61-6aa80e4fdee3" alt=""><figcaption></figcaption></figure>


---

# 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://help.sdocs.com/s-sign/advanced-signer-scenarios/signer-authentication/cac-piv-verification.md?ask=<question>&goal=<user_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.
