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

# Testing external authentication

> Test your External Identity Provider configuration by running a test-challenge URL in your browser before applying the provider to a Vantage tenant.

Before applying an External Identity Provider to your tenant, test your parameters to confirm Vantage can authenticate through it.

## Test an External Identity Provider

<Steps>
  <Step title="Open the test-challenge URL in your browser">
    Use the URL shape that matches your protocol, filling in the parameters from the [Parameters](#parameters) reference below. For fully composed examples, see [Sample links](#sample-links).

    **OAuth 2.0:**

    ```
    https://<your-vantage-url>/api/v1/external/test-challenge?settings=<settings>&returnUrl=<returnUrl>
    ```

    **SAML 2.0:**

    ```
    https://<your-vantage-url>/api/v1/external/test-challenge?settings=<settings>&returnUrl=<returnUrl>&tenantId=<tenantId>
    ```
  </Step>

  <Step title="Authenticate with the External Identity Provider">
    Enter your credentials on the Identity Provider's sign-in page.
  </Step>

  <Step title="Check the result">
    One of three things happens:

    * **Success with a `returnUrl`** — Vantage redirects you to the URL specified in `returnUrl`. The address bar shows the authenticated user's username and email.
    * **Success without a `returnUrl`** — Vantage redirects you back to the page you opened the test link from.
    * **Failure** — An authentication error appears on the Identity Provider's sign-in page. Check your parameters and run the test again.
  </Step>
</Steps>

## Parameters

| Parameter   | Required for        | Description                                                                                                                                         |
| :---------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| `settings`  | OAuth 2.0, SAML 2.0 | JSON describing the External Identity Provider. Shape varies by protocol — see below.                                                               |
| `returnUrl` | OAuth 2.0, SAML 2.0 | The URL Vantage redirects to after a successful test. For testing, use any Vantage endpoint like `/skills`. The URL root is embedded automatically. |
| `tenantId`  | SAML 2.0 only       | The Vantage tenant identifier used for authentication.                                                                                              |

### `settings` for OAuth 2.0

| Field                | Description                                                  |
| :------------------- | :----------------------------------------------------------- |
| `Kind`               | `AzureActiveDirectoryOidc` or `OnPremiseActiveDirectoryOidc` |
| `Settings.Authority` | URL of the External Identity Provider                        |
| `Settings.ClientId`  | Client ID of the Identity Provider                           |

Example:

```json theme={null}
{
  "Kind": "AzureActiveDirectoryOidc",
  "Settings": {
    "Authority": "https://login.microsoftonline.com/11112222-3333-4444-5555-666677778888",
    "ClientId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
  }
}
```

### `settings` for SAML 2.0

| Field                  | Description                                    |
| :--------------------- | :--------------------------------------------- |
| `Kind`                 | `Saml2`                                        |
| `Settings.MetadataUri` | URL of the Federation Metadata document        |
| `Settings.OwnEntityId` | Application ID URI in the form `api://<appId>` |

Example:

```json theme={null}
{
  "Kind": "Saml2",
  "Settings": {
    "MetadataUri": "https://login.microsoftonline.com/11112222-3333-4444-5555-666677778888/federationmetadata/2007-06/federationmetadata.xml",
    "OwnEntityId": "api://cccc3333-dddd-4444-eeee-5555ffff6666"
  }
}
```

## Sample links

<Accordion title="Sample link (OAuth 2.0)">
  ```
  https://vantage-eu.abbyy.com/auth2/api/v1/account/external/test-challenge?settings={"Kind":"AzureActiveDirectoryOidc","Settings":{"Authority":"https://login.microsoftonline.com/11112222-3333-4444-5555-666677778888","ClientId":"aaaabbbb-0000-cccc-1111-dddd2222eeee"}}&returnUrl=/skills
  ```
</Accordion>

<Accordion title="Sample link (SAML 2.0)">
  ```
  https://vantage-eu.abbyy.com/auth2/api/v1/account/external/test-challenge?settings={"Kind":"Saml2","Settings":{"MetadataUri":"https://login.microsoftonline.com/11112222-3333-4444-5555-666677778888/federationmetadata/2007-06/federationmetadata.xml","OwnEntityId":"api://cccc3333-dddd-4444-eeee-5555ffff6666"}}&returnUrl=/skills&tenantId=your_vantage_tenant_id
  ```
</Accordion>

## Related topics

<CardGroup cols={2}>
  <Card title="Setting up an External Identity Provider" icon="shield-halved" href="/vantage/documentation/tenant-admin/tenant-management/external-identity-provider">
    Overview of OAuth 2.0 and SAML 2.0 provider setup
  </Card>

  <Card title="Setting up an External Identity Provider for a tenant" icon="sliders" href="/vantage/documentation/tenant-admin/tenant-management/configuring-tenant">
    Apply the External Identity Provider to your tenant
  </Card>

  <Card title="Configuring an OAuth 2.0 External Identity Provider" icon="key" href="/vantage/documentation/tenant-admin/tenant-management/oauth-2-0">
    AD FS or Azure AD with OAuth 2.0
  </Card>

  <Card title="Configuring a SAML 2.0 External Identity Provider" icon="shield-halved" href="/vantage/documentation/tenant-admin/tenant-management/saml-2-0">
    AD FS or Azure AD with SAML 2.0
  </Card>
</CardGroup>