Configure OIDC Connection

Applies to VirtServer 3.21.0, last modified on June 11, 2024

What is OpenID Connect?

OpenID Connect is a protocol that sits on top of the OAuth 2.0 framework. Where OAuth 2.0 provides authorization via an access token containing scopes, OpenID Connect provides authentication by introducing a new token, the ID token which contains a new set of scopes and claims specifically for identity. With the ID token, OpenID Connect adds structure and predictability to allow otherwise different systems to interoperate and share authentication state and user profile information.

VirtServer supports connection with OIDC. When configured user authentication will be delegated to the OAuth Identity Provider and the Virtserver admin does not have to do user management (create, remove, modify user info, etc.) in Virtserver anymore. However, the admin can still do authorization for virts to individual users or groups of users.

Supported OIDC providers : OKTA

There are 2 OAuth flows that Virtserver allows to log into Virtserver via an OAuth IDP.

  • PKCE Flow (for the Virtserver UI, ReadyAPI integration, and the Virtserver CLI used by a human).

  • Client Credentials Flow (for Virtserver CLI used in a machine-machine mode. e.g., in CI systems).

Either of these authentication flows may be used to grant admin or regular privileges in Virtserver. Regular privileges allow you to do virt-level tasks such as starting/stopping/deploying/undeploying/tagging virts etc. Admin privileges allow you to do all of the above and additionally start/stop/activate-license to the Virtserver. To facilitate this authorization certain claims are used which are explained below.

The PKCE flow requires the following information in the access token JWT
Audit Log

Click the image to enlarge it.

  1. aud claim that matches the oidcAuthorizationServerAudience property in the virt-server.yml configuration.

  2. sub claim that returns the IdP unique ID of the user in IdP.

  3. groups_access claim that returns the user groups assigned to the user. The name of this claim and which groups are eligible for admin and regular privileges in Virtserver are configurable via the virt-server.yml. Please see settings oidcGroupNameField, oidcAdminGroupFilter, and oidcUserGroupFilter in the VirtServer Settings
  4. app_type claim with the value Web

    .
The Client Credentials flow requires the following information in the access token JWT
Audit Log

Click the image to enlarge it.

  1. aud claim that matches the oidcAuthorizationServerAudience property in the virt-server.yml configuration.

  2. sub claim that returns the client ID of the configured application.

  3. A scope in the scp claim with either of the scope values vs_cli_admin or vs_cli_regular depending on the Virtserver privileges to be assigned to that client app.
  4. app_type claim with the value Web

    .

Okta configuration for VirtServer PKCE flow

You may need to contact an OKTA admin in your organization for these configurations. The OKTA setup below is for a normal OKTA organization. Your OKTA Admin may modify it to fit with existing configurations of apps other than Virtserver.

Pre-requisites

  • Have a properly configured OKTA Organization.

  • Login to OKTA Admin console with the necessary Admin Access.

  • Already have users in OKTA.

Step 1: Configure a Virtserver PKCE App in OKTA.

Refer to OKTA help for creating an app.

  • Log in to the Okta Admin Panel.

  • Navigate to Applications > Applications from the left floating panel.

  • Click the Create App Integration Button.

  • Select Sign-in method = OIDC and Application type = Native Application.

  • Provide an App Integration Name (e.g. Virtserver).

  • Select the following grant types:

    • Authorization Code
    • Refresh Token
    • Device Authorization (Needed for Virtserver CLI authentication)
  • Set Sign-in redirect URIs = https://<your-virtserver-domain>:9090/virtserver/auth

  • Set Sign-out redirect URIs = https://<your-virtserver-domain>:9090/virtserver/login

  • Select Controlled access = Skip group assignment for now

  • Save the changes.

Please note the generated Client ID as you will need it later when configuring Virtserver. This will be used for the oidcClientId param in the .yml.

Step 2: Create a new authorization server

Refer to OKTA help for creating groups.

  • Go to the SecurityAPI from the left floating panel.

  • Click Add Authorization Server. Note down the Audience value you enter (e.g. virtserver) for later use in the VirtServer configuration. This will be used for the oidcAuthorizationServerAudienceparam in the yml.

  • Also, note down the generated Issuer URI for the authorization server for later use in the VirtServer configuration. This will be used for the oidcProviderUrlparam in the yml.

  • Click on the link for the authorization server just created.

  • Create a claim called groups_access

    1. Select the Claims tab and click Add Claim button.

    2. Name the claim “groups_access”. This claim is configurable via the Virtserver configuration’s OIDC section. The param oidcGroupNameField in the config yml should be the same as this claim name.

    3. Include in token type = Access Token,

    4. Value type = Groups
    5. Value Type = Matches regex .*
    6. Include in = Any scope

    7. Click the Save button
  • Create a claim called app_type
    1. Select Claims tab and click Add Claim button

    2. Name the claim “app_type”
    3. Include in token type = Access Token,
    4. Value Type = Expression
    5. Value = String.stringContains(access.scope, "vs_cli") ? "CLI" : "Web"
    6. Include In = Any scope
    7. Click the Save button
  • Click Access Policies tab. Then click Add New Access Policy button.

  • Set any Name for the policy. for e.g., Virtserver PKCE

  • Assign To: select the radio button The following clients: and select the client created in Step 1.
  • For the newly created access policy, click the Add rule button.
  • Ensure the following grant types are only selected - Authorization Code, Implicit (hybrid), Resource Owner Password, Device Authorization
  • Ensure that for the User is rule section the value Any user assigned the app radion button is selected.

  • Ensure that the Scopes requested rule section has the Any scopes radio button selected.
  • Save the rule.

Step 3: Configure Trusted Origins

Refer to OKTA help for creating API access claims.

  • Go to the SecurityAPI from the left floating panel.

  • Click on the Tab Trusted origins.

  • Click button Add origin.

  • Enter origin name and origin url: https://<your-virtserver-domain>:9090

  • For the Choose type prompt, select all options

  • Save changes

Set up OIDC connection in VirtServer config

  • Configure your OIDC connection details in VirtServer settings file virt-server.yml

    # OIDC Settings
    oidcConfiguration:
     # Client id. This should be provided by your OIDC admin from the Virtsever app config
       oidcClientId: '0oad4h2tg5mnJIJ2C5d7'
      # Provider url. This should be provided by your OIDC admin based on your okta org
      # oidcProviderUrl: 'https://<your okta org url>/oauth2/default'
       oidcProviderUrl: 'https://dev-06865876.okta.com/oauth2/default'
      # Token revocation url. Should be the same as in your OIDC provider
      # oidcTokenRevocationUrl: 'https://<your okta org url>/oauth2/default/v1/revoke'
       oidcTokenRevocationUrl: 'https://dev-06865876.okta.com/oauth2/default/v1/revoke'
      # Authorization Audience URI. To be provided by the OIDC admin based on the Audience URI / Entity ID configured for the authorization server
      oidcAuthorizationServerAudience: 'api://default'

    To get client ID you need to login to Okta Admin Panel, go to Applications > Applications from left floating panel. You can copy Client ID value under a name of the Application Integration you have created.
    Provider URL is visible in the top right corner of the page after you click on your email address.
  • Start / Re-start Virtserver.

  • Users can now go to https://localhost:9090/virtserver#/

  • Users will be invited to login via OIDC.

    login via OIDC
  • If login fails, an error message will pop-up on the screen.

    login via OIDC Error
  • After successful login, the user will be re-directed to VirtServer UI.

    Note: User management is exclusively controlled in Okta, and editing user data and privileges directly in VirtServer is restricted.
  • After successful authentication and adding as an admin or user, VirtServer functions normally, granting access to its features and capabilities as expected.

  • Users logging into VirtServer via OIDC with the "VirtServer Admin" role obtain administrator privileges, while those logging in with the "VirtServer User" role get user permissions. To upgrade a user to an admin role, they must first be added to the "VirtServer Admin" group in Okta.

  • Once admins and user log in using an Okta account, they appear in the Users list.

  • User cannot use LDAP and regular login methods on the same VirtServer instance if OIDC is configured.

For Device login in OKTA

Client Credentials App related configuration in OKTA

Step 1: Configure a Virtserver Client Credentials App in OKTA.

Refer OKTA help for creating an app.

  • Log in to Okta Admin Panel
  • Navigate to ApplicationsApplications from the left floating panel.
  • Click Create App Integration Button.
  • Select Sign-in method = API Services.
  • Provide an App Integration Name (e.g. Virtserver).
Note down the generated Client ID and Client Secret for later use in Virtserver CLI.

Step 2: Configure the authorization server.

  • Go to the Security → API from the left floating panel.
  • Select the Virtserver specific authorization server created earlier during Step 2 of the PKCE configuration.
  • Click the Scopes tab. Add 2 new scopes - vs_cli_admin and vs_cli_regular. For adding each scope use the following settings:
    • Click Add Scope button
    • Name = vs_cli_admin
    • User Consent = Implicit
    • Default scope = select checkbox Set as a default scope
    • Click Create button
    • Repeat steps a - e for vs_cli_regular
  • Click Access Policies tab. Then click Add New Access Policy button.

  • Set Name for the policy: Virtserver CLI Admin

  • Assign To: select the radio button The following clients: and select the client created in Step 1 if it is designated to be granted Admin privileges in Virtserver.
  • For the newly created access policy, click the Add rule button.
  • Ensure the following grant types is only selected - Client Credentials.
  • Ensure that for the User is rule section the value Any user assigned the app radion button is selected.

  • Ensure that the Scopes requested rule section has the The following scopes radio button selected and select the scope vs_cli_admin.
  • Save the rule.

  • Click Access Policies tab. Then click Add New Access Policy button.

  • Set Name for the policy: Virtserver CLI Admin

  • Assign To: select the radio button The following clients: and select the client created in Step 1 if it is designated to be granted Regular privileges in Virtserver.
  • For the newly created access policy, click the Add rule button.
  • Ensure the following grant types is only selected - Client Credentials.
  • Ensure that for the User is rule section the value Any user assigned the app radion button is selected.

  • Ensure that the Scopes requested rule section has the The following scopes radio button selected and select the scope vs_cli_regular.
  • Save the rule.

Note: Creating both access policies is created Virtserver CLI Admin and Virtserver CLI Regular is a one-time configuration. More Client Credentials Apps can be added to either access policy depending on the Virtserver privileges needed.

CLI Log in - Using Client Credentials

Log in using the following configuration (updating with the correct CLI version and your specific URL).

java -jar <path to virtserver cli jar> -s localhost:9090 -login -clientid <client id> -clientsecret <client secret>

After logging in, user can run other CLI commands to deploy, start, stop services, list services.

CLI Log in - Using Device Authentication

  • Login using the following configuration (updating with correct CLI version and your specific URL).

    java -jar <path to virtserver cli jar> -s localhost:9090 -login
  • After running login command user sees link with activation code

    Go to url https://<your okta org url>/activate?user_code=FAKEKDVV on any device to finish authentication.

  • User needs to activate device by copying the above link, opening it in a browser and login to Okta.

    After log in, user can deploy, start, stop, and list services.

Logout via CLI

Logout using the following configuration (updating with correct CLI version and your specific URL).

java -jar <path to virtserver cli jargt; -s localhost:9090 -logout
Note: When the user logs out, oidc.json is removed. They cannot use CLI and need to log in and activate their device again. The user cannot continue to use CLI after logout.

If user tries to run any command via CLI while logged out, an error message Cannot obtain the token from VirtServer. is displayed.

Note:
  • Users who log in to VirtServer using OIDC initially do not have administrator permissions unless added to the VirtServer Admin group in Okta.

  • Once a user logs in using an OIDC account, they will appear in the Users list. The profile update button is greyed out when logged in through OIDC. Changes can only come from Okta.

  • You can only use OIDC if configured for OIDC, you will not be able to use LDAP and regular login methods on the same VirtServer instance.

  • To remove a user, they should be removed from the corresponding Virtserver group in the OIDC provider. (The user will remain in the Virtserver database for the current implementation, but they cannot log in).

  • Users can log in via CLI, VS web UI, or ReadyAPI (tokens are not the same).

  • When a user logs in for the first time, a new User is created in VirtServer db and is visible in the Users table in UI.

  • If configuration with Okta is disabled, the user can use CLI in a standard way.

  • Device activation on the same device (desktop) or mobile device works properly.

  • Device activation using login/password to Okta or GitHub account works.

  • If the user is not logged in to Okta by GitHub when activating the device, they need to log in and go back again to the page. Repeat the step to activate the device (this behavior is generated by Okta, not related to VirtServer).

  • User management via CLI is not possible for an OIDC-enabled Virtserver.

See Also

VirtServer Settings
Admin Tasks

Highlight search results