Configuring and Managing Federation with OAuth

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: Starting with VMware Cloud Director API v. 31.0, OAuth login is based on OpenID Connect.

Prerequisites

This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights. Verify that you are logged in to the vCloud Air Compute Service as an Account Administrator.

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 similar to:

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

2. To add your identity provider's OAuth metadata, modify the retrieved OrgOAuthSettings element.
   This metadata includes the service's public key, issuer identifier, a URL to which you can make an authentication request, at least one key configuration, access token endpoint, user authorization endpoint, and user information endpoint. See Update Organization OAuth Settings.

   To retrieve user information, you must use either the UserInfoEndpoint or the ScimEndpoint element. If you want to retrieve group information, you must use the ScimEndpoint element. When using the UserInfoEndpoint element, optionally, you can customize the key names by using the OIDCAttributeMapping element.

   Note: Starting with VMware Cloud Director API version 38.0, the ScimEndpoint field is deprecated.

   Note: If you are using VMware Identity Manager ^® as your OAuth identity provider, you must use the ScimEndpoint element.

3. Update the OrgOAuthSettings with your modifications.
   1. Find the Link element in the settings element where rel="edit".
   2. 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 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 xmlns="http://www.vmware.com/vcloud/v1.5">
    <IssuerId>http://IDP.example.com/oauth2</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>
    <ClientId>clientId</ClientId>
    <ClientSecret>clientSecret</ClientSecret>
    <UserAuthorizationEndpoint>https://IDP.example.com/oauth2/authorize</UserAuthorizationEndpoint>
    <AccessTokenEndpoint>https://IDP.example.com/oauth2/access_token</AccessTokenEndpoint>
    <UserInfoEndpoint>https://IDP.example.com/oauth2/userinfo</UserInfoEndpoint>
    <Scope>openid</Scope>
    <Scope>email</Scope>
    <Scope>profile</Scope>
        <OIDCAttributeMapping>
     <SubjectAttributeName>sub</SubjectAttributeName>
     <EmailAttributeName>email</EmailAttributeName>
     <FirstNameAttributeName>givenname</FirstNameAttributeName>
     <LastNameAttributeName>surname</LastNameAttributeName>
     <GroupsAttributeName>groups</GroupsAttributeName>
     <RolesAttributeName>roles</RolesAttributeName>
    </OIDCAttributeMapping>
    <MaxClockSkew>60</MaxClockSkew>
</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>http://IDP.example.com/oauth2</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>
    <ClientId>clientId</ClientId>
    <ClientSecret>clientSecret</ClientSecret>
    <UserAuthorizationEndpoint>https://IDP.example.com/oauth2/authorize</UserAuthorizationEndpoint>
    <AccessTokenEndpoint>https://IDP.example.com/oauth2/access_token</AccessTokenEndpoint>
    <UserInfoEndpoint>https://IDP.example.com/oauth2/userinfo</UserInfoEndpoint>
    <Scope>openid</Scope>
    <Scope>email</Scope>
    <Scope>profile</Scope>
        <OIDCAttributeMapping>
     <SubjectAttributeName>sub</SubjectAttributeName>
     <EmailAttributeName>email</EmailAttributeName>
     <FirstNameAttributeName>givenname</FirstNameAttributeName>
     <LastNameAttributeName>surname</LastNameAttributeName>
     <GroupsAttributeName>groups</GroupsAttributeName>
     <RolesAttributeName>roles</RolesAttributeName>
    </OIDCAttributeMapping>
    <MaxClockSkew>60</MaxClockSkew>
</OrgOAuthSettings>