If you want to import users and groups from an OpenID Connect (OIDC) identity provider to your VMware Cloud Director system organization, you must configure your system organization with this OIDC identity provider. Imported users can log in to the system organization with the credentials established in the OIDC identity provider.

OAuth is an open federation standard that delegates user access. OpenID Connect is an authentication layer on top of the OAuth 2.0 protocol. By using OpenID Connect, clients can receive information about authenticated sessions and end-users. The OAuth authentication endpoint must be reachable from the VMware Cloud Director cells which makes it more suitable when you use public identity providers or provider managed ones.

You can configure VMware Cloud Director to automatically refresh your OIDC key configurations from the JWKS endpoint you provide. You can configure the frequency of the key refresh process and the rotation strategy that determines whether VMware Cloud Director adds new keys, replaces the old keys with new, or the old keys expire after a certain period.

Note: For successful VMware Cloud Director integration with external identity providers, to determine the correct values and settings and to ensure proper and accurate configuration, see also the product documentation of those identity providers.

VMware Cloud Director generates audit events for both successful and failed key refreshes under the event topic com/vmware/vcloud/event/oidcSettings/keys/modify. The audit events for failed key refreshes include additional information about the failure.

Procedure

  1. From the primary left navigation panel, select Administration.
  2. In the left panel, under Identity Providers, click OIDC.
  3. If you are configuring OIDC for the first time, copy the client configuration redirect URI and use it to create a client application registration with an identity provider that complies with the OpenID Connect standard, for example, VMware Workspace ONE Access.
    You need this registration to obtain a client ID and a client secret that you must use during the OIDC identity provider configuration.
  4. Click Configure.
  5. Verify that OpenID Connect is active, and enter the client ID and client secret information from the OIDC server registration.
  6. (Optional) To use the information from a well-known endpoint to automatically fill in the configuration information, turn on the Configuration Discovery toggle and enter a URL at the site of the provider that VMware Cloud Director can use to sent authentication requests to.
  7. Click Next.
  8. If you did not use Configuration Discovery in Step 6, enter the information in the Endpoints section.
    1. Enter the endpoint and issuer ID information.
    2. If you are using VMware Workspace ONE Access as an identity provider, select SCIM as access type. Starting with VMware Cloud Director 10.4.1, the SCIM option is deprecated.
      For other identity providers, you can leave the default User Info selection.
    3. If you want to combine claims from the UserInfo endpoint and the ID Token, turn on the Prefer ID Token toggle.
      The identity providers do not provide all the required claims set in the UserInfo endpoint. By turning on the Prefer ID Token toggle, VMware Cloud Director can fetch and consume claims from both sources.
    4. Enter the maximum acceptable clock skew.
      The maximum clock skew is the maximum allowable time difference between the client and server. This time compensates for any small time differences in the timestamps when verifying tokens. The default value is 60 seconds.
    5. Click Next.
  9. If you did not use Configuration Discovery in Step 6, enter the scope information, and click Next.
    VMware Cloud Director uses the scopes to authorize access to user details. When a client requests an access token, the scopes define the permissions that this token has to access user information.
  10. If you are using User Info as an access type, map the claims and click Next.
    You can use this section to map the information VMware Cloud Director gets from the user info endpoint to specific claims. The claims are strings for the field names in the VMware Cloud Director response.
  11. If you want VMware Cloud Director to automatically refresh the OIDC key configurations, turn on the Automatic Key Refresh toggle.
    1. If you did not use Configuration Discovery in Step 6, enter the Key Refresh Endpoint.
      The Key Refresh Endpoint is a JSON Web Key Set (JWKS) endpoint and it is the endpoint from which VMware Cloud Director fetches the keys.
    2. Select how often the key refresh occurs.
      You can set the period in hourly increments from 1 hour up to 30 days.
    3. Select a Key Refresh Strategy.
      Option Description
      Add

      Add the incoming set of keys to the existing set of keys. All keys in the merged set are valid and usable.

      For example, your existing set of keys includes keys A, B, and D. Your incoming set of keys includes keys B, C, and D. When the key refresh occurs, the new set includes keys A, B, C, and D.
      Replace

      Replace the existing set of keys with the incoming set of keys.

      For example, your existing set of keys includes keys A, B, and D. Your incoming set of keys includes keys B, C, and D. When the key refresh occurs, key C replaces key A. The incoming keys B, C, and D become the new set of valid keys without any overlap with the old set.
      Expire After

      You can configure an overlap period between the existing and incoming sets of keys. You can configure the overlapping time using the Expire Key After Period, which you can set in hourly increments from 1 hour up to 1 day.

      The key refresh runs start at the beginning of every hour. When the key refresh occurs, VMware Cloud Director tags as expiring the keys in the existing set of keys that are not included in the incoming set. At the next key refresh run,VMware Cloud Director stops using the expiring keys. Only keys included in the incoming set are valid and usable.

      For example, your existing set of keys includes keys A, B, and D. The incoming set includes keys B, C, and D. If you configure the existing keys to expire in 1 hour, there is 1 hour overlap during which both sets of keys are valid. VMware Cloud Director marks key A as expiring and until the next key refresh run, keys A, B, C, and D are usable. At the next run, key A expires and only B, C, and D continue working.
  12. For VMware Cloud Director 10.5.1 and later, if you did not use Configuration Discovery in Step 6, upload the private key that the identity provider uses to sign its tokens.
  13. If you want to customize the Sign in with OIDC button label that appears on the VMware Cloud Director login page, enter a new custom button text.

    You can enter up to 24 symbols. You can use special characters and accented letters. If you want to revert to the default text, delete the custom label. The default button label is localized, and depending on your browser language settings, the text might appear in a different language. Custom labels always appear as you enter them.

  14. Click Save.

What to do next

  • Subscribe to the com/vmware/vcloud/event/oidcSettings/keys/modify event topic.
  • Verify that the Last Run and the Last Successful Run are identical. The runs start at the beginning of the hour. The Last Run is the time stamp of the last key refresh attempt. The Last Successful Run is the time stamp of the last successful key refresh. If the time stamps are different, the automatic key refresh is failing and you can diagnose the problem by reviewing the audit events.