This page provides an overview of the key features of the API portal for VMware Tanzu.
The page at
/apis shows all API Groups registered in the portal. Each group is represented as a card that contains a title and short description. You can filter by title/description using the field located at the top-right corner.
You can inspect and try out an API by following the VIEW DETAILS link. This view presents:
If an endpoint is protected, a lock icon is shown at the right of the endpoint description, and you will need authorization information in order to access that endpoint.
In order to try out a protected endpoint, you must generate the authorization information. You can do this by clicking on the lock button or Authorize button at the top. This will bring up a dialog showing all available authorization methods described in the OpenAPI specification for the selected API group. Methods include:
The most commonly used authentication methods are OpenID, OAuth 2.0, and Bearer Authentication. These are discussed in the following sections.
Note: If your authorization server and API are hosted in different domains, see the CORS section.
OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory. OIDC defines a sign-in flow that enables a client application to authenticate a user and obtain information (or "claims") about that user, such as the username, email address, and so on.
User identity information is encoded in a secure JSON Web Token (JWT), called an ID token. OpenID Connect defines a discovery mechanism, OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, such as:
For this method, the authorization dialog will show different OpenID strategies that you can use to obtain a token, which will be included as a header in the protected API requests.
The Authorization Code Flow allows you to obtain a token for accessing the protected API. In order to start this flow, you must specify the
If the server was configured to use Proof Key for Code Exchange (PKCE), which is intended for public clients that cannot hide the secret, then you can leave the
client_secret field empty.
This example requires an Okta account. You can create a new developer account at the Okta Developer Portal.
Note: The Single-Page Application selection is important when configuring PKCE. If the API will be used on the server-side, or if the API is proxied by Spring Cloud Gateway, use non-PKCE methods for now.
[API-PORTAL-HOST]is the host used by API portal). API portal will ask Okta to redirect to
/oauth2-redirect.htmlto complete the authorization code flow, and Okta must recognize this as a valid redirect.
After these steps, Okta will provide a Client ID.
Note: If you are using Spring Cloud Gateway, it must be configured to use the simple Okta
authorization_code (no PKCE) method, because it is not a public client. In the third step above, select Web Application. Okta will provide a Client Secret along with the Client ID. Okta services require that the request is not from a browser, and you cannot use a Client ID without PKCE configuration from the API portal.
You will receive an Issuer ID and the
./well-known/openid-configuration required by the OpenAPI spec of the API that requires authorization in the API portal.
Google Cloud does not permit PKCE. When using Google Cloud, you must always include the Client Secret for any authorization code flow.
In the Google Cloud console:
This method exposes a dialog to enter a token that will be included as
Authorization: Bearer <token> header key-value pair.
If your API uses OAuth 2.0 or OpenID, you must manually follow the authorization code flow to generate a valid token.
Postman can act as a client and obtain an authorization code (including PKCE).
https://oauth.pstmn.io/v1/callback, and verify that your authorization server has this URL as a valid login redirect. This URL is similar to the redirect URL used by the API portal. It will capture the authorization code to request a token.
.well-known/openid-configurationendpoint (for example,
.well-known/openid-configurationendpoint (for example,
openidand any other scope you need.
Ensure that your browser can open new tabs automatically from the callback URL. This will generate a new token that can be seen in Postman and used in the API portal.
The CORS protocol is used by the agent (usually a browser) to check whether an API can be used by the current origin.
The API portal domain needs to be accepted as valid cross-origin. Verify the following:
Access-Control-Allow-Origin): a list of comma-separated values. This list must include your API portal host and SSO host if you are using OpenID dialogs.
Access-Control-Allow-Method): must allow the method used by your API. Also check that your API and the authorization server support preflight requests (a valid response to the OPTIONS HTTP method).
Access-Control-Allow-Headers): if the API requires any header, you must include it in the API configuration or your authorization server.
For the authorization server, check your provider and configure a specific section for
Originheader value of the request.
A valid OPTIONS response should include the origin where the API portal is hosted in the
curl -I -k \ -X 'OPTIONS' \ -H 'Connection: keep-alive' \ -H 'Pragma: no-cache' \ -H 'Cache-Control: no-cache' \ -H 'Accept: */*' \ -H 'Origin: https://myapi-portal.somedomain.example.spring.io' \ -H 'Access-Control-Request-Method: POST' \ -H 'Access-Control-Request-Headers: content-type' \ "https://vmware.okta.com/.well-known/openid-configuration"
As shown in the following response, the origin
https://myapi-portal.somedomain.example.spring.io is a valid origin, so the API portal can request the necessary OpenID configuration. The
.well-known/openid-configuration is public and could be included in any page. Because of this, Okta and other authorization servers always include the
Origin request header as the value of the
HTTP/2 200 date: Thu, 16 Sep 2021 07:42:55 GMT content-type: application/octet-stream content-length: 0 server: nginx access-control-allow-origin: https://myapi-portal.somedomain.example.spring.io access-control-allow-credentials: true access-control-allow-methods: GET, OPTIONS access-control-allow-headers: content-type vary: Origin
Your API should also include the API portal (and your application clients) in the allowed origin list. If the API portal is a valid origin, any request from the browser will succeed. Keep in mind that you must first click the Authorize button to get a token, and then that token will be included in the requests as an
If the application you want to use for the API is located at:
and the API portal is located at:
Then the API provider must respond with a header such as:
so that both the application and the API portal can send requests to the API.
Important: For a production environment, you must strictly configure the allowed origin list and avoid a wildcard
* that would allow an attacker to use your API without user interaction in any webpage.