Setting Up SSO Authentication with External Identity Providers

Configuring CData Virtuality Authentication Management Component

In this guide, we describe how to configure the CData Virtuality Authentication Management Component via a browser (to follow the steps, first log in to the Authentication Management Component, for example, localhost:8080).

Creating a Realm

• Provide a name, for example, CDVSERVER_SSO. The name is the only detail needed for realm setup.

• The Create realm button is available via the menu in the upper left corner.

• Always ensure that you work in that newly created realm and not in the master realm, especially after a fresh login.

Creating a Client

Enter the following values:

• Client type: OpenID Connect

• Client ID: provide an ID (name), for example, cdvserver_sso_client

Setting up Access Settings for Your Client in the CData Virtuality Authentication Management Component

Go to your realm → your client → Settings and set up the Capability config:

• Turn on Client authentication.

• Set up the Authentication flow. Choose the following values:

  • Standard flow

  • Implicit flow

  • Direct access grant

  • Service accounts role

Add the following Valid redirect URIs:
<CData Virtuality server URL, for example, http://localhost:8180 >/*;

Add the following Web origins:
<CData Virtuality server URL>

Setting up Service Account Roles

Go to your realm → your client → Service account roles and assign the following roles:

• realm-management view-users - to allow import/refresh of users;

• realm-management view-realm - to allow import/refresh of roles.

Configuring Identity Provider

Initial Setup

1. Open the Identity Providers menu of your realm.

2. Add the OpenID Connect provider.

3. Provide an alias and optionally a display name.

4. Provide the details obtained from the external Identity Provider:

   1. OpenID Connect metadata document URL as discovery URL;

   2. Client ID;

   3. Client Secret.

5. Save the Identity Provider configuration

6. After saving, do the following:

   • Extract/copy the URL shown as redirectUrl. 

   • This URL must be set up as a redirectUrl on your external Identity Provider (see Configure the Sign-in redirect URIs in the Okta application section in Okta SSO for SaaS).

Users and Roles

Users and roles can be loaded to the Authentication Management Component using Identity Provider extension or by using Mappers.

Setting Up Mappers

Create a Mapper to assign the Identity Provider groups to the Authentication Management Component roles. The Mapper menu is available via Identity Providers → Identity Provider added on previous step → Mapper tab. Indicate the following values:

1. Name: provide a name for the mapper to be created.

2. Sync mode override: Force.

3. Mapper type: Claim to Role.

4. Claim: groups.

5. Claim Value: the id or the name for the Identity Provider group. Examples:

   1. Azure: 59def5b5-b0a5-443f-ab8d-f3de1782fd8a

   2. Okta: CDV-Admin

6. Role:  Authentication Management Component role name. To see the realm roles in the assignment dialogue, please use the Filter by realms option in the interface.

Configure one mapper per Identity Provider group that shall be mapped to a CData Virtuality Authentication Management Component/CData Virtuality Server role.

Setting Up Extensions

The extension allows importing and synchronizing users and roles from external Identity Providers into the CData Virtuality OAuth2 Server. Currently, the extension is supported only for Okta. For details on how to configure the Okta extension, see Okta SSO for SaaS.

Configuring CData Virtuality Server

Setting the Option Values

Set up the following CData Virtuality Authentication Management Component option values:

Examples

CALL "SYSADMIN.setDefaultOptionValue"(
    "opt" => 'DV_AUTH_SERVER_URL'
    , "val" => ' http://localhost:8081/realms/CDVSERVER_SSO/.well-known/openid-configuration');;

CALL "SYSADMIN.setDefaultOptionValue"(
    "opt" => 'DV_AUTH_REALM'
    , "val" => 'CDVSERVER_SSO');; 

CALL "SYSADMIN.setDefaultOptionValue"(
    "opt" => 'DV_AUTH_CLIENT_ID'
    , "val" => 'cdvserver_sso_client';; 

CALL "SYSADMIN.setDefaultOptionValue"(
    "opt" => 'DV_AUTH_CLIENT_SECRET
    ', "val" => 'HCPYEWeiknqUOtwFRXWnodDPDSmmpCng');; 

CALL "SYSADMIN.setDefaultOptionValue"(
    "opt" => 'DV_AUTH_LOAD_USERS'
    , "val" => true);; 

CALL "SYSADMIN.setDefaultOptionValue"(
    "opt" => 'DV_AUTH_LOAD_ROLES'
    , "val" => true);;

Loading SSO Roles and Users

To load the SSO roles and users, connect to the СData Virtuality Server using the standard СData Virtuality authentication mechanism as admin and run the SYSADMIN.refreshSSOUserCache procedure:

CALL "SYSADMIN.refreshSSOUserCache"();;

Roles and users will be loaded.

The loaded external Identity Provider roles and users end in -@SSO (e.g. admin-role@SSO, user_1@SSO, etc.), and user-role mapping can be seen in SYSADMIN.UserRoles after SSO users and roles are loaded.

If you want to refresh the roles and users in the CData Virtuality Server explicitly (for example, after manually removing a user or a role from the Authentication Management Component), call theSYSADMIN.refreshSSOUserCachestored procedure.

When using Mappers, users are added only after their first successful login. When using the extension, users are loaded along with their roles after executing SYSADMIN.refreshSSOUserCache.

Setting Permissions

Permissions can be set in one of two ways. You can choose either of them, but we do not recommend mixing them.

1. By setting permissions for an object to the SSO role:

CALL "SYSADMIN.setPermissions"(
    "role_name" => 'admin-role@SSO',
    "resourceName" => '*',
    "permissions" => 'CRUDEAL'
);;

2. By mapping SSO roles to CData Virtuality roles. In this case, all the permissions from the CData Virtuality role will be granted to the SSO role:

CALL "SYSADMIN.setPermissions"(
    "role_name" => 'admin-role@SSO',
    "mapToRole" => 'admin-role'
);;

Connecting to CData Virtuality Server using Web UI

After the DV_AUTH option values are set, roles and users are loaded and permissions are set, you can connect to the CData Virtuality Server via SSO using the SSO authentication wizard.

The default parameters, such as the CData Virtuality Authentication Management Component URL, client ID, and client secret, are set in the dvserver\standalone\deployments\api.war\WEB-INF\classes\service-on-premise.properties file.

To modify these parameters, unzip the api.war file, change the parameters as needed, and then zip it back and redeploy api.war.

Example of the settings:

• oidc.server.client.id=dvserver_sso_client

• oidc.server.config.url=http://localhost:8081/realms/CDVSERVER_SSO/.well-known/openid-configuration

• oidc.server.client.secret=HCPYEWeiknqUOtwFRXWnodDPDSmmpCng

• oidc.server.use_dv_roles=true

Connecting to CData Virtuality Server using Studio

After the DV_AUTH option values are set, roles and users are loaded and permissions are set, you can connect to the CData Virtuality Server using the OAuth 2.0 authentication with access/refresh tokens. For details on how to obtain tokens, see the Obtaining Access and Refresh Tokens section below.

Connecting to CData Virtuality Server using JDBC driver

After the DV_AUTH option values are set, roles and users are loaded and permissions are set, you can connect to the CData Virtuality Server using the OAuth 2 authentication.

To do this, set the authType=OAUTH2 parameter to use OAuth 2 authentication. Use access/refresh tokens to connect. For details on how to obtain tokens, see the Obtaining Access and Refresh Tokens section below.

Connection string example:

jdbc:cdatavirtuality:datavirtuality@mms://localhost:31001;authType=OAUTH2;accessToken=<token>;refreshToken=<token>

Obtaining Access and Refresh Tokens

To obtain Okta users access and refresh tokens, follow these steps:

1. Get authorization code:

   1. URL to obtain authorization code: <CData Virtuality Authentication Management Component URL>/realms/<your realm name>/protocol/openid-connect/auth?response_type=code&client_id=<your client id>&redirect_uri=http://localhost/;

   2. Select Okta and login using standard Okta authorization;

   3. Copy code from the redirected URL:

      

2. Get access and refresh tokens:

   1. URL to get tokens: <CData Virtuality Authentication Management Component URL>/realms/<your realm name>/protocol/openid-connect/token;

   2. Parameters in request body:

      • grant_type = authorization_code

      • client_id = <your client id>

      • client_secret = <your client secret>

      • redirect_uri = http://localhost/

      • code = from Step 1

3. Use the returned access and refresh tokens while connecting via CData Virtuality Studio and JDBC/ODBC clients.