This page provides an overview of the key features of the API portal for VMware Tanzu.

Overview

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:

  • The API group title and description
  • The servers available for testing endpoints, along with any applicable authorization configuration
  • Information about the API endpoints (grouped by sections), including HTTP method, relative URL, and a short description (click on an endpoint for more details)

API Authorization

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:

  • HTTP Basic Authentication
  • API Keys
  • Bearer Authentication
  • OAuth 2.0
  • OpenID
  • Cookie Authentication

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

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:

https://server.com/.well-known/openid-configuration

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.

Authorization Code

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 client_id and scopes.

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.

Example: Configuring Okta for Authorization Code + PKCE

This example requires an Okta account. You can create a new developer account at the Okta Developer Portal.

  1. Go to Applications > Applications.
  2. Click on Create App Integration.
  3. A dialog will show several options. Select OIDC - OpenID Connect, and then select Single-Page Application.

    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.

  4. Click Next.
  5. In the Sign-in redirect URIs section, include the URI https://[API-PORTAL-HOST]/oauth2-redirect.html (where [API-PORTAL-HOST] is the host used by API portal). API portal will ask Okta to redirect to /oauth2-redirect.html to complete the authorization code flow, and Okta must recognize this as a valid redirect.
  6. Select one of the Assignments to control access.

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.

  1. Navigate to Security > API.
  2. Click Add Authorization Server.
  3. In the dialog, fill in the name and paste the Client ID in the Audience field.

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.

Example: Configuring Google Cloud for Authorization Code

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:

  1. Navigate to APIs & Services > Credentials.
  2. Click + Create Credentials.
  3. Select OAuth client ID.
  4. Add your callback URI in the Authorized redirect URIs list.
  5. Save the configuration.
  6. Copy the provided Client ID and Client Secret.

Bearer Authorization

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.

Example: Using Postman to Generate a Token

Postman can act as a client and obtain an authorization code (including PKCE).

In Postman:

  1. Create a new request.
  2. In the Authorization tab, select type OAuth 2.0.
  3. In the Configure New Token options, select the Grant Type that you wish to use (in this example, Authorization Code, with or without PKCE).
  4. Leave the Callback URL set to 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.
  5. Enter the Auth URL. You can find this URL in the .well-known/openid-configuration endpoint (for example, https://dev-xxxx.okta.com/oauth2/default/v1/authorize).
  6. Enter the Access Token URL. You can find this URL in the .well-known/openid-configuration endpoint (for example, https://dev-xxxx.okta.com/oauth2/default/v1/token).
  7. Enter the Client ID.
  8. If the authorization server does not have PKCE enabled, enter the Client Secret.
  9. Set the scope to include openid and any other scope you need.
  10. Provide a value for the State field (required).
  11. Click Get New Access Token to initiate the authorization flow.

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.

CORS

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:

  • Origins allowed (header: 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.
  • Methods allowed (header: 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).
  • Headers allowed (header: Access-Control-Allow-Headers): if the API requires any header, you must include it in the API configuration or your authorization server.

Example

For the authorization server, check your provider and configure a specific section for Trusted Origins.

Some examples:

  • Okta: can be found in the Applications group. See Enable CORS in the Okta documentation.
  • Google Cloud: the headers are automatically populated based on the Origin header value of the request.

A valid OPTIONS response should include the origin where the API portal is hosted in the Access-Control-Allow-Origin header:

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 Access-Control-Allow-Origin.

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 Authorization header.

If the application you want to use for the API is located at:

https://my-spa-app.vmware.net

and the API portal is located at:

https://api-portal.vmware.net

Then the API provider must respond with a header such as:

Access-Control-Allow-Origin: https://my-spa-app.vmware.net,https://api-portal.vmware.net

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.

check-circle-line exclamation-circle-line close-line
Scroll to top icon