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.
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.
1 | Retrieve your organization's OrgOAuthSettings. 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 Example: 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. | ||||
3 | Update the OrgOAuthSettings with your modifications.
|
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.
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.
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>