An organization can define an external identity provider that supports OAuth 2.0 authentication, as defined in RFC 6749. All organizations that participate in an OAuth-based federated identity scheme must include an OrgOAuthSettings element whose IssuerId and OAuthKeyConfigurations were retrieved from the same identity provider.

Note

When an organization is created, it is provided with a self-signed certificate for use when establishing trust with an identity provider. This certificate expires after one year. You can regenerate this certificate by making a request of the following form. 

POST https://vcloud.example.com/api/admin/org/id/settings/federation/action/regenerateCertificate

You can retrieve this certificate with a request of the following form, where name is the name of the organization. 

GET https://vcloud.example.com/cloud/org/name/saml/metadata/alias/vcd

You do not have to be authenticated to make this request.

Prerequisites

This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights.

Select an OAuth service that supports OAuth 2.0. To enable your organization to use this service, you must obtain the service's public key and related information that the OrgOAuthSettings element of your organization's Settings element requires.

Procedure
1

Retrieve your organization's OrgOAuthSettings.

Use a request like this one: 

GET https://vcloud.example.com/api/admin/org/40/settings/oauth
2

Modify the retrieved OrgOAuthSettings element to add your identity provider's OAuth metadata.

This metadata includes the service's public key, issuer identifier, a URL to which you can make an authentication request, and at least one key configuration. See Example: Update Organization OAuth Settings.

3

Update the OrgOAuthSettings with your modifications.

a

Find the Link element in the settings element where rel="edit".

b

Make a PUT request to the URL in that link's href attribute value, and supply the modified section as the request body. See the request portion of Example: Update Organization Federation Settings.

Example: Update Organization OAuth Settings

This example updates the OrgOAuthSettings of an organization whose URL is https://vcloud.example.com/api/admin/org/40/. The update adds information retrieved from an identity provider, and enables OAuth federation by setting Enabled to true.

Request: 

PUT https://vcloud.example.com/api/admin/org/40/settings/oauth
Content-Type: application/vnd.vmware.admin.organizationOAuthSettings+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgOAuthSettings
   <IssuerId>https://IDP.example.com/oauth/token</IssuerId>
   <OAuthKeyConfigurations>
      <OAuthKeyConfiguration>
         <KeyId>f2842a04-a172-407d-bac3-20f4a175af3e</KeyId>
         <Algorithm>RSA</Algorithm>
         <Key>-----BEGIN PUBLIC KEY----- 
         MIIBIjANBgk... 
         ...
         -----END PUBLIC KEY-----
         </Key>
      </OAuthKeyConfiguration>
   </OAuthKeyConfigurations>
   <Enabled>true</Enabled>
</OrgOAuthSettings>

The response contains information extracted from the request, and includes Link elements that the server creates.

Response: 

200 OK
Content-Type: application/vnd.vmware.admin.organizationOAuthSettings+xml
...
<OrgOAuthSettings
         href="https://vcloud.example.com/api/admin/org/40/settings/oauth"
         type="application/vnd.vmware.admin.organizationOAuthSettings+xml">
         <Link
            rel="up"
            href="https://vcloud.example.com/api/admin/org/40/settings"
            type="application/vnd.vmware.admin.orgSettings+xml" />
         <Link
            rel="edit"
            href="https://vcloud.example.com/api/admin/org/40/settings/oauth"
            type="application/vnd.vmware.admin.organizationOAuthSettings+xml" />
   <IssuerId>https://IDP.example.com/oauth/token</IssuerId>
   <OAuthKeyConfigurations>
      <OAuthKeyConfiguration>
         ...
      </OAuthKeyConfiguration>
   </OAuthKeyConfigurations>
   <Enabled>true</Enabled>
</OrgOAuthSettings>