Setting up an External Identity Provider for a tenant

Once you’ve prepared an External Identity Provider (see Configuring an OAuth 2.0 External Identity Provider or Configuring a SAML 2.0 External Identity Provider) and tested it, connect it to your Vantage tenant.

This setup requires the Tenant Administrator role.

When you enable an External Identity Provider, the Resource Owner Password Credentials authentication flow stops working for this tenant.

Connect an External Identity Provider to your tenant

Open the Identity Provider settings

In Vantage, click Configuration in the left pane, then click Identity Provider.

Switch to External Identity Provider

In the top drop-down, select External Identity Provider.

Choose your protocol

In the Protocol field, select OAuth 2.0 or SAML 2.0. The settings panel updates with protocol-specific fields. See OAuth 2.0 fields or SAML 2.0 fields for details on each field.

Fill in the protocol-specific fields

Enter the values from the provider you prepared earlier.

External Identity Provider configuration — OAuth 2.0 with Azure AD

(Optional) Add associated email domains

Under Associated Email Domains, click + Add Domain URL, enter the domain (for example, example.com) in the Domain URL field, and click Apply. Repeat to add more. For more information, see Associated email domains.

Apply the configuration

Click Apply Changes.

Reverting to the Vantage Identity Provider. To undo, select Vantage in the top drop-down and click Apply Changes. You can do this as long as your current session (access token) hasn’t expired. If it has expired, you’ll need to sign in through the configured External Identity Provider to regain access — contact your System Administrator if you’re locked out.

OAuth 2.0 fields

Field	Description
Identity Provider	The type of provider. Choose Active Directory Federation Services (AD FS), Azure Active Directory (Azure AD), or Other for any OAuth 2.0-compatible provider.
Identity Provider URL	URL of the Identity Provider. In Azure, find it in the Endpoints section of your registered application.
Client ID	Client identifier of the application registered in your Identity Provider.
Client Secret	(Visible only when Identity Provider* is set to Other.)* The client secret of the registered application.
Associated Email Domains	Email domains whose users can sign in to this tenant, even if they don’t have a Vantage account yet. See Associated email domains.

SAML 2.0 fields

Field	Description
Federation Metadata Document URL	URL of your Identity Provider’s SAML 2.0 federation metadata document.
Application ID URI	(Optional.) A custom URI that identifies your Vantage application to the Identity Provider (for example, `api://<appId>`). If left empty, the obsolete default `api://platform.abbyy.cloud/{tenantId}` is used, where `tenantId` is the Vantage tenant identifier in GUID format without hyphens (for example, `117489fc1aea41658369d4d18d6557ga`).
Associated Email Domains	Email domains whose users can sign in to this tenant, even if they don’t have a Vantage account yet. See Associated email domains.

Setting up default roles for new users

When users are created automatically through an External Identity Provider, Vantage assigns them the default roles you configure here.

Open the Identity Provider settings

In Vantage, click Configuration in the left pane, then click Identity Provider and select External Identity Provider from the top drop-down.

Select default roles

In the Default Roles For New Users field, select one or more roles to automatically assign to new users.

Apply the configuration

Click Apply Changes.

For each selected role, the Allow all current and further skills toggle is on by default, giving new users access to every skill in the tenant. You can adjust this later for individual users from the Users page. See Role-based access control for details on each role.

Configuring a SAML 2.0 External Identity Provider without an XML file URL

You can configure Vantage to use a SAML 2.0 External Identity Provider by copying the contents of your XML metadata file to the Vantage API request. The contents of XML file should contain the information necessary for interacting with SAML-enabled Identity Providers. To configure a SAML 2.0 External Identity Provider via the Vantage API, do the following:

Authorize in the Vantage API (see Authentication documentation for details).
Send a PUT request with the Authorization = Bearer <access token> header to https://<your-vantage-url>/api/adminapi2/v2/tenants/<tenantId>/external-providers/ with the following request body parameters:

Parameter	Description
kind	The protocol used. The value of the parameter is Saml2.
settings.Metadata	The contents of your XML metadata file.

Sample request:

For Windows

curl --location --request PUT "https://<your-vantage-url>/api/adminapi2/v2/tenants/<tenantId>/external-providers/"
-H "Authorization: Bearer <token>"
{
  "providerSettings": {
    "kind": "Saml2",
    "settings": {
      "Metadata": "<SAML XML file contents>"
    }
  }
}

For Linux

curl --location --request PUT 'https://<your-vantage-url>/api/adminapi2/v2/tenants/<tenant-id>/external-providers/'
-H 'Authorization: Bearer <token>'
{
  'providerSettings': {
    'kind': 'Saml2',
    'settings': {
      'Metadata': '<SAML XML file contents>'
    }
  }
}