Using VMware Cloud Director as an Identity Provider Proxy Server

Starting with version 10.4.2, you can use VMware Cloud Director as a tenant-aware identity provider proxy server.

When VMware Cloud Director is configured as an identity provider proxy server by using the OAuth 2.0 OpenID Connect standard, relying parties can use VMware Cloud Director for tenant-aware authentication of users known to VMware Cloud Director. For detailed information on the OpenID Connect standard, see OpenID Connect Core 1.0.

As an identity provider proxy server, VMware Cloud Director acts as intermediary between the client application (relying party) and the identity provider, and delegates actual authentication to the respective authentication mechanism used by the provider or tenants.

A system administrator can configure relying parties that integrate with VMware Cloud Director and then enable individual tenants to allow their users to use VMware Cloud Director as an identity provider proxy.

Authentication Flow

Integration with VMware Cloud Director is implemented through the OAuth 2.0 OIDC authorization code flow standard. For detailed information, see Authentication using the Authorization Code Flow.

When a relying party redirects a user to VMware Cloud Director, if there is no existing client session, the user is prompted to log in to VMware Cloud Director by first identifying the organization or provider portal they wish to log into. The user authenticates through the configured authentication mechanism, which may involve further redirections to external identity providers. If the user's browser detects an existing VMware Cloud Director user session, the authentication flow provides an SSO experience and no user interaction is required for reauthentication. Upon successful completion of the process, VMware Cloud Director returns an access token and an ID token. The authorization code that is issued as part of the flow is valid for 5 minutes. The access token is valid for 5 minutes, and the ID token is valid for an hour.

Note:

VMware Cloud Director does not return a refresh token.

You cannot use the access token that VMware Cloud Director returns upon successful authentication for accessing the UI portals or for making regular VMware Cloud Director API calls.

ID Token Details

The ID token that VMware Cloud Director returns contains the following OpenID standard claims and VMware Cloud Director specific claims.

Claim	Description
`at_hash`	(OpenID standard claim) Access token hash value.
`sub`	(OpenID standard claim) The `userId` in VMware Cloud Directorin UUID format.
`iss`	(OpenID standard claim) Public address of VMware Cloud Director.
`preferred_username`	(OpenID standard claim) User name of the user in VMware Cloud Director
`nonce`	(OpenID standard claim) String value used to associate a client session with an ID token, and to mitigate replay attacks. Only present if it was initially included in the relying party request.
`aud`	(OpenID standard claim) The audience for this token. The value is the client ID of requesting relying party.
`azp`	(OpenID standard claim) Authorized party for the token. The value is the client ID of the relying party. Its value is same as the `aud` claim.
`name`	(OpenID standard claim) Full name of the user, if known to VMware Cloud Director.
`phone_number`	(OpenID standard claim) Phone number of the user, if known to VMware Cloud Director.
`exp`	(OpenID standard claim) Expiration time. Time after which the ID token is not accepted for processing.
`iat`	(OpenID standard claim) Time at which the ID token was issued.
`email`	(OpenID standard claim) Email address of the user, if known to VMware Cloud Director.
`roles`	(VMware Cloud Director custom claim) An array of the names of the roles the user has in VMware Cloud Director.
`groups`	(VMware Cloud Director custom claim) An array of the names of the groups in which the user belongs in VMware Cloud Director.
`org_name`	(VMware Cloud Director custom claim) Name of the organization in which the user is logged in.
`org_display_name`	(VMware Cloud Director custom claim) Display name of the organization.
`org_id`	(VMware Cloud Director custom claim) The organization ID in UUID format.

OpenID Request Scopes

The scope of the OpenID request is used to specify the privileges requested for an access token.

Scope Values	Description.
`openid`	Required. OpenID standard scope.
`profile`	OpenID standard scope. Requests access to the end-user default profile claims.
`email`	OpenID standard scope. Requests access to the end-user email address claims.
`groups`	OpenID standard scope. Requests access to the groups that the user is part of in VMware Cloud Director.
`phone`	OpenID standard scope. Requests access to the user phone number claim.
`vcd_idp`	VMware Cloud Director specific scope. Requests access to VMware Cloud Directorcustom claims, such as `roles`, `groups`, `org_name`, `org_display_name`, and `org_id`.

Endpoints

You can use the access token returned by VMware Cloud Director to retrieve claims about the authenticated user at the hostname/oidc/UserInfo endpoint. For details, see UserInfo Endpoint.
You can retrieve the provider configuration values, including the JWKS endpoint and information about other endpoints and scopes necessary for the OIDC proxy configuration at the well-known configuration URL hostname/oidc/.well-known/openid-configuration. See View the OIDC Proxy General Settings in Your VMware Cloud Director.

Token Exchange Access to VMware Cloud Director Identity Provider Proxy

Programmatic integration with the identity provider proxy functionality of VMware Cloud Director is available through the token exchange flow that is detailed below. This flow does not involve the VMware Cloud Director UI and is suitable for scripted access, such as CLI.

Obtain a VMware Cloud Director JWT by either directly logging in or by using an API token.

Run a POST request.

POST  hostname/oidc/oauth2/token

Select x-www-form-urlencoded for the body of the request.

Include the following parameters in the body of the request.

{
     "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
     "assertion": "VMware_Cloud_Director JWT",
     "client_id": "Relying_party_ID",
     "scope": "openid profile email phone groups vcd_idp",
   }

The response returns both an ID token that includes the OIDC and VMware Cloud Director claims, and an access token that you can use to retrieve claims about the authenticated user at the hostname/oidc/UserInfo endpoint.

Encoded ID token example:

eyJhbGciOiJSUzI1NiIsInR5NDg4SI6I................4dHnbU1RQ6Y9Yohgw

Decoded ID token example:

{
  "at_hash": "1AA1aAA1AAAAAAaAA1A11a",
  "sub": "111111111-1111-1111-1111-11111111",
  "roles": [
    "Organization Administrator"
  ],
  "iss": "https://hostname/oidc",
  "groups": [
    "ALL USERS"
  ],
  "preferred_username": "testuser@vcd-ms1",
  "nonce": "ab123acab",
  "aud": "33333333-3333-3333-3333-33333333333",
  "azp": "22222222-2222-2222-2222-22222222",
  "org_id": "12345678-1234-1234-1234-123456789abc",
  "org_display_name": "oidcorg",
  "name": "test user",
  "phone_number": " ",
  "exp": 1111111111,
  "org_name": "oidcorg",
  "iat": 1111111111,
  "email": "[email protected]"
}

User Info response example:

{
    "sub": "111111111-1111-1111-1111-11111111",
    "preferred_username": "administrator",
    "name": "administrator user",
    "email": "[email protected]",
    "phone_number": "0 (111) 222-3333",
    "roles": [ "system administrator" ],
    "groups": [],
    "org_name": "system",
    "org_display_name": "System Organization",
    "org_id": "12345678-1234-1234-1234-123456789abc"
}

Multisite Considerations

In a multisite deployment, each site functions as a single identity provider server.

Paired sites do not provide federated identity server support. This means that if during the login process a tenant that does not belong to the site that functions as their identity provider proxy attempts to login to it through the organization selection of another site of the multisite deployment, login fails.