Setting Up SSO Authentication

Configuring CData Virtuality OAuth 2 Server

Use a browser to log in to CData Virtuality OAuth 2 Server, for example, localhost:8080.

Realm

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

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

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

Client

To create a client, go to Your realm → Clients → Create client. Enter the following details:

“Client type”: "OpenID Connect".
“Client ID”: provide an ID (name), for example, cdvserver_sso_client.

Set Up Client Settings

Set up access settings for your client in the CData Virtuality OAuth 2 server:

Go to Your realm → Your client → Settings.
Add the following Valid redirect URIs:
<CData Virtuality server URL, for example, http://localhost:8180 >/*;
Add the following Web origins:
<CData Virtuality server URL>

Set up login settings. Turn off Consent required in the same client settings.

Set up service account roles:

Go to Your realm → Your client → Service account roles.
Assign the following roles:
- realm-management view-users
- realm-management view-realm

Roles

You can create realm or client roles.

Realm Roles

Go to Your realm → Realm roles → Create role.

Provide a name, for example, admin-role. The name is the only detail needed for role setup.

Client roles

Go to Your realm → Clients → Your client → Roles → Create role.

Provide a name, for example, odata-role. The name is the only detail needed for role setup.

Users

To create a user, go to Your realm → Users → Add user.

Provide a name, for example, test_user1. Click Create.

Set User Credentials

Go to User → Credentials → Set password.

Set password;
Turn off Temporary.

Assign Role to a User

You can assign realm or client role to a user.

Go to User → Role mapping → Assign role.

Filter by realm or client. Search for a role;
Select role and click Assign.

Using SSO for Authentication in CData Virtuality Server

To use SSO for authentication, configure the connection parameters in the CData Virtuality Server and load the SSO users and roles.

Setting the Option Values

You need to set following CData Virtuality OAuth 2 server option values:

Option Value	Description	Location in the CData Virtuality OAuth 2 Server
`DV_AUTH_SERVER_URL`	The “.well-known” discovery url for the realm	Realm Settings -> OpenID Endpoint Configuration
`DV_AUTH_REALM`	The name of the realm	Realm Settings -> Realm name
`DV_AUTH_CLIENT_ID`	The ID of the client	Clients -> Client details -> Settings -> Client ID
`DV_AUTH_CLIENT_SECRET`	The clientSecret of the client	Clients -> Client details -> Credentials -> Client Secret
`DV_AUTH_LOAD_USERS`	Controls whether users are imported from CData Virtuality Auth Management	`TRUE`
`DV_AUTH_LOAD_ROLES`	Controls whether roles are imported from CData Virtuality Auth Management	`TRUE`

Example

CODE

CALL "SYSADMIN.setDefaultOptionValue"("opt" => 'DV_AUTH_SERVER_URL', "val" => <СData Virtuality OAuth 2 server configuration URL. E.g. http://localhost:8080/realms/<realm name>/.well-known/openid-configuration);;
CALL "SYSADMIN.setDefaultOptionValue"("opt" => 'DV_AUTH_REALM', "val" => <your realm name taken from СData Virtuality OAuth 2 server>);;
CALL "SYSADMIN.setDefaultOptionValue"("opt" => 'DV_AUTH_CLIENT_ID', "val" => <client ID taken from СData Virtuality OAuth 2 server>);;
CALL "SYSADMIN.setDefaultOptionValue"("opt" => 'DV_AUTH_CLIENT_SECRET', "val" => <client secret taken from СData Virtuality OAuth 2 server>);;
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

Connect to the СData Virtuality Server using the standard СData Virtuality authentication mechanism as admin and follow these steps:

Run the SYSADMIN.refreshSSOUserCache procedure:

CODE

CALL "SYSADMIN.refreshSSOUserCache"();;

SSO roles and users will be loaded.

SSO roles and users have @SSO ending (e.g. admin-role@SSO, user_1@SSO, etc.), and SSO user-role mapping can be seen in SYSADMIN.UserRoles after SSO users and roles are loaded.

Set permissions for SSO roles.

Permissions can be set in one of two ways:

By setting permissions for an object to the SSO role:

CODE

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

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:

CODE

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

Connecting to CData Virtuality Server via SSO 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 via SSO using the OAuth 2/OpenID authentication.

You can use username/password or access/refresh tokens to connect.

Version 4.10 and older

The URL is the СData Virtuality OAuth 2 Server URL, e.g. http://localhost:8080>/realms/<realm name>/.well-known/openid-configuration.

Client credentials for connection are the same as for the corresponding DV_AUTH option values.

Version 4.11 and above

The configuration URL, client ID, and client secret are no longer set in the CData Virtuality Studio.

Connecting to CData Virtuality Server via SSO 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 OAuth 2 server 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.

Connecting to CData Virtuality Server via SSO using JDBC clients

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 OAuth 2/OpenID authentication.

Set the authType=OAUTH2 parameter to use OAuth 2 authentication.

You can use username/password or access/refresh tokens to connect.

Version 4.10 and older

Client credentials for the connection are the same as the DV_AUTH option values and should be passed in the connection string.

Connection string example:

CODE

jdbc:datavirtuality:datavirtuality@mm://localhost:31200;SHOWPLAN=ON;configurationUrl=http://localhost:8080/realms/odata-oauth/.well-known/openid-configuration;clientId=<client_Id>;clientSecret=<client_secret>;authType=OAUTH2

Version 4.11 and above

Connection string example:

CODE

jdbc:datavirtuality:datavirtuality@mm://localhost:31000;authType=OAUTH2;accessToken=<token>;refreshToken=<token>

configurationUrl, clientId, and clientSecret JDBC properties are deprecated and will be ignored if included in the connection string.

configurationUrl, clientId, and clientSecret JDBC properties have been deprecated since v4.11