VMware Identity Broker - vCenter Server

VMware Identity Broker - vCenter Server

This API Reference provides documentation, descriptions, and request/response samples for the VCF Identity Broker REST APIs.

What is VCF Identity Broker

VCF Identity Broker is VMware's dedicated authentication solution which helps provide a centralized authentication source for the VCF components. Starting with VCF 9.0 you can use VCF Identity Broker to achieve single sign-on (SSO) and access VCF components such as vCenter, VCF Operations, VCF Automation, VCF Operations for logs, VCF Operations for networks, VCF Operations orchestrator, and NSX Manager, with one set of credentials.

Supported Identity Providers and Protocols

Modern Identity Providers:

  • Okta
  • Ping Identity
  • Microsoft Entra ID
  • Microsoft Active Directory Federation Services (ADFS)
  • Any SAML 2.0 Identity Providers

Directory-Based Identity Providers:

  • AD/LDAP
  • OpenLDAP

The authentication protocols supported are:

  • Security Assertion Markup Language (SAML 2.0) - A well-established XML-based protocol where the identity provider issues digitally signed XML-based assertions to the service provider for user authentication.
  • OpenID Connect protocol (OIDC) - A modern authentication protocol built on OAuth 2.0, where the identity provider issues an ID token in JSON format for user authentication.

As part of configuring VCF SSO, you can create/modify/delete users and groups in the VCF Identity Broker provisioned from the identity provider. The following protocols are supported:

  1. SCIM 2.0 (System for Cross-domain Identity Management)
  2. JIT (Just-In-Time)
  • Just-In-Time Group Provisioning - Groups are created dynamically based on the SAML assertion when the user logins in for the first time. You can use group pre-provisioning if you know the group names from the identity provider that requires entitlements.
  • JIT pre-provisioning of groups - You create the required groups in advance to perform role assignments. Users will be assigned to these groups dynamically on their first login based on SAML assertion. Only the groups pre-provisioned are available for role assignments.
  1. AD/LDAP (Active Directory over LDAP)

VMware Identity Broker API Use Cases

  1. To authenticate users from your applications to VCF, use Authentication OAuth APIs
  2. To create OIDC clients in VCF Identity Broker to connect applications to VCF SSO use Administration OAuth 2 Client APIs

Request Failures

API errors are reported using standard HTTP status codes.

  • HTTP 4XX codes are returned when the request contains bad syntax or cannot be fulfilled
  • HTTP 5XX codes are returned when something is wrong with the server

Authorization errors will be denoted by either HTTP 401 (Unauthorized) or HTTP 403 (Forbidden). These kinds of errors are usually access token related and can be cleared by making sure that the token is present and has not expired.

An API will return HTTP 444 (No Response) (with no response body) when the request's Host header does not match the server's fully qualified domain name.

For all errors the API's response body includes the error code and additional error message in the format below:

"errors": [
    {
        "code": "oauth2.client.with.client.id.already.exists",
        "message": "OAuth2 Client with client id {client_id} already exists.",
        "parameters": {
            "oauth2_client_id": "{client_id}"
        }
    }
]