VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Federate
vCenter Server
 to Microsoft Active Directory Federation Services (AD FS)
Last Updated December 16, 2024

You can federate
vCenter Server
 to Microsoft Active Directory Federation Services (AD FS) as an external identity provider by using the
vCenter Server
Identity Providers
 service.
This process of configuring an AD FS identity provider requires that you have administrative access to both your
vCenter Server
 and your AD FS server. During the configuration process, you enter information first in your
vCenter Server
, then in your AD FS server, then in your
vCenter Server
.
Active Directory Federation Services requirements:
  • AD FS for Windows Server 2016 or later must already be deployed.
  • AD FS must be connected to Active Directory.
  • An Application Group for
    vCenter Server
     must be created in AD FS as part of the configuration process. See the VMware knowledge base article at https://kb.vmware.com/s/article/78029.
  • An AD FS server certificate (or a CA or intermediate certificate that signed the AD FS server certificate) that you add to the Trusted Root Certificates Store.
  • You have created a
    vCenter Server
     administrators group in AD FS that contains the users you want to grant
    vCenter Server
     administrator privileges to.
For more information about configuring AD FS, see the Microsoft documentation.
vCenter Server
 and other requirements:
  • vSphere 7.0 or later
  • vCenter Server
     must be able to connect to the AD FS discovery endpoint, and the authorization, token, logout, JWKS, and any other endpoints advertised in the discovery endpoint metadata.
  • You need the
    VcIdentityProviders
    Manage
     privilege to create, update, or delete a
    vCenter Server
     Identity Provider that is required for federated authentication. To limit a user to view the Identity Provider configuration information only, assign the
    VcIdentityProviders
    Read
     privilege.
  1. Authenticate to the
    vSphere Automation
     API endpoint and establish a session.
  2. Add your AD FS root CA certificate to the Trusted Root Certificates Store.
  3. Fill in the
    oidc
     data structure by using the Application Group configuration from AD FS.
    Parameter
    Description
    discovery_endpoint
    The OpenID address of the AD FS server.
    client_id
    The client identifier of the AD FS Application Group.
    client_secret
    The secret shared between the client and the provider.
    claim_map
    This parameter is required but not applicable to AD FS. Use an empty array
    []
    .
  4. Fill in the
    active_directory_over_ldap
     data structure.
    Parameter
    Description
    user_name
    The user name of a user in the domain who has a minimum of read-only access to the base Distinguished Name (DN) for users and groups.
    password
    The password of a user in the domain who has a minimum of read-only access to the base DN for users and groups.
    users_base_dn
    The base DN for users in the Active Directory environment connected to AD FS that you want to be able to federate with
    vCenter Server
    .
    groups_base_dn
    The base DN for groups in the Active Directory environment connected to AD FS that you want to be able to federate with
    vCenter Server
    .
    server_endpoints
    Active Directory server endpoints. At least one Active Directory server endpoint must be set.
    Use the format:
    ldap://<
    hostname
    >:<
    port
    >
     or
    ldaps://<
    hostname
    >:<
    port
    >
    . The port is typically 389 for LDAP connections and 636 for LDAPS connections. For Active Directory multi-domain controller deployments, the port is typically 3268 for LDAP and 3269 for LDAPS.
    cert_chain
    The SSL certificate chain in base64 encoding. You can skip this parameter only if all the Active Directory server endpoints use the LDAP (and not the LDAPS) protocol.
  5. Add the identity provider by using the service.
    1. Fill in the request body parameters.
      Parameter
      Description
      config_tag
      The configuration type of the identity provider. The possible values are
      Oauth2
       and
      Oidc
      . For AD FS federation, use
      Oidc
      .
      name
      The user-friendly name for the identity provider. For proper configuration, you must use the exact string
      Microsoft ADFS
      .
      upn_claim
      The name of the claim in the AD FS JWT token that contains the user principal name (UPN) of the user that is logging in. You must use the same value that you used when you set up the AD FS Application Group. The procedure from the article in the prerequisites uses
      upn
      . If unset, the default value is
      acct
      .
      groups_claim
      The name of the claim in the AD FS JWT token that contains the group membership of the user that is logging in. You must use the same value that you used when you set up the AD FS Application Group. The procedure from the article in the prerequisites uses
      group
      . If unset, the groups for the subject consist of the groups in
      group_names
       and
      group_ids
       claims.
      is_default
      Set to
      true
      . Specifies whether the provider is the default provider. Setting
      is_default
       to
      true
       makes all other providers non-default.
      If unset:
      • In case it is the first created provider, it is set as the default provider.
      • In case it is not the first created provider, it is not set as the default provider.
      oidc
      Data structure for
      oidc
      .
      idm_protocol
      The communication protocol used to connect to AD FS to search for users and groups when assigning permissions in
      vCenter Server
      . You must use
      LDAP
      . If unset, no communication protocol is configured for the users and groups search.
      active_directory_over_ldap
      Data structure for
      active_directory_over_ldap
      .
    2. Invoke the operation.
      POST https://<vcenter_server_ip_address_or_fqdn>/api/vcenter/identity/providers
      The operation returns the ID of the provider you created.
  6. Configure
    vCenter Server
     permissions for Active Directory users or groups in your AD FS environment.
    You can do this in two ways:
    • Add a user from your AD FS environment to a group in
      vCenter Server
      .
    • Configure Global Permissions for an AD FS user.
    In vSphere 8.0 and later, you cannot configure permissions through the
    vSphere Automation
     API. Instead, you use either the
    vSphere Client
     or the vSphere Web Services API. For more information, see the
    vSphere Authentication Guide
     or the
    vSphere Web Services SDK Programming Guide
    .
  7. Copy the two redirect URIs from the Identity Provider Configuration page in the
    vSphere Client
     and add them to your AD FS Application Group.
    You must do this step to enable logging in to
    vCenter Server
     through AD FS by using the
    vSphere Client
    .
You configured
vCenter Server
 to use AD FS as the identity provider.

Content feedback and comments