Configure OIDC Connection

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

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

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 Security → API 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 Security → API 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

• 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.

  

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

  

• 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.

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 Applications → Applications 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.

CLI Log in - Using Client Credentials

CLI Log in - Using Device Authentication

Logout via CLI