OAuth Client Web Services

Owned by Stonebranch
Last updated: Nov 17, 2022
7 min read

Overview

Universal Controller supports the following RESTful-based web services for OAuth Client operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about parameter requirements, are provided.

Create an OAuth Client 


 Description

URI

http://host_name/uc/resources/oauthclient

HTTP Method

POST

Description

Creates an OAuth Client.

Example URI

http://localhost:8080/uc/resources/oauthclient

Authentication

HTTP Basic

Produces Content-Type

n/a

Consumes Content-Type

application/xml, application/json

Example Responses

  • Status 200

    • Successfully created the OAuth Client with id {uuid}.

  • Status 400

    • Error message.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • An OAuth Client with name “{name}” does not exist.

    • An OAuth Client with id "{uuid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

OAuth Client Properties 

Property

UI Field Name

Description

Specifications

Required

authorizationEndpoint

Authorization Endpoint

The authorization endpoint for the authorization server. 

Read only. 

Y

clientId

Client ID

The Client ID issued by the authorization server.


N

clientSecret

Client Secret

The Client secret issued by the authorization server.


Y

clusterRedirectUrls

Cluster Node Redirect URLs

List of Redirect URLS.

XML

<clusterRedirectUrls>
    <clusterRedirectUrl>
        <clusterNode>node1:8080-uc</clusterNode>
        <redirectUrl>http://localhost:8080/uc/oauth2/callback</redirectUrl>
    </clusterRedirectUrl>
</clusterRedirectUrls>

JSON

"clusterRedirectUrls": [
    {
        "clusterNode": "node1:8080-uc",
        "redirectUrl": "http://localhost:8080/uc/oauth2/callback"
    }
]


N

description

Description

Description of this record.


N

exportReleaseLevel

n/a

Universal Controller release that the record was exported from.

read only

N

exportTable

n/a

Record table information.

read only

N

name

Name

Name used within the Controller to identify this OAuth Client.

Maximum 100 alphanumerics.

Y

opswiseGroups

Member of Business Services

List of Business Services:
 
XML

<opswiseGroups>
	<opswiseGroup>test</opswiseGroup>
</opswiseGroups>

JSON

"opswiseGroups": [
    "test"
]


N

provider

Provider

The authentication server provider.

The Provider property cannot be changed after the OAuth Client is created.

Valid Values:

  • As String = Azure AD, As Value = 1

  • As String = Google, As Value = 2

Y

retainSysIds

n/a

Specification for whether or not the Create an OAuth Client web service will persist the sysId property.

  • If retainSysIds="true" and sysId is included in the request/response, sysId will be persisted to the database.

  • If retainSysIds="false" and sysId is included in the request/response, sysId will be ignored; it will be autogenerated by the Controller.

Note

In XML web services, retainSysIds is specified as an attribute in the <calendar> element.

Valid values: true/false (default is true).

N

scopes

Scopes

List of scopes to request access to.

XML

<scopes>
	<scope>https://mail.google.com</scope>
</scopes>

JSON

"scopes": [
    "https://mail.google.com"
]



Y

sysId

UUID

System ID field in the database for this OAuth Client record.

Persisted only if retainSysIds is set to true.

N

tenantIdTenant ID If provider is Azure AD; The tenant identifier. If not specified, defaults to common. 
N

tokenEndpoint

Token Endpoint

The token endpoint for the authorization server. 

Read only. 

N

Create an OAuth Client: XML and JSON Examples 


XML

JSON

Example Request
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthClient retainSysIds="true">
    <clientId>client_id</clientId>
    <clientSecret>client_secret</clientSecret>
    <clusterRedirectUrls>
        <clusterRedirectUrl>
            <clusterNode>node1:8080-uc</clusterNode>
           <redirectUrl>http://localhost:8080/uc/oauth2/callback</redirectUrl>
        </clusterRedirectUrl>
    </clusterRedirectUrls>
    <description>description</description>
    <name>Google</name>
    <opswiseGroups/>
    <provider>Google</provider>
    <scopes>
        <scope>https://mail.google.com</scope>
    </scopes>
    <sysId>239119555c2c427f8f5b29faeecfdc27</sysId>
</oauthClient>
 JSON
{
    "clientId": "client_id",
    "clientSecret": "client_secret",
    "clusterRedirectUrls": [
        {
          "clusterNode": "node1:8080-uc",
          "redirectUrl":"htttp://localhost:8080/uc/oauth2/callback"
        }
    ],
    "description": "description",
    "name": "Google",
    "opswiseGroups": [],
    "provider": "Google",
    "retainSysIds": true,
    "scopes": [
        "https://mail.google.com"
    ],
    "sysId": "239119555c2c427f8f5b29faeecfdc27"
}

Modify an OAuth Client 


 Description

URI

http://host_name/uc/resources/oauthclient

HTTP Method

PUT

Description

Modifies an OAuth Client.

Example URI

http://localhost:8080/uc/resources/oauthclient

Authentication

HTTP Basic

Produces Content-Type

n/a

Consumes Content-Type

application/xml, application/json

Example Responses

  • Status 200

    • Successfully updated the OAuth Client with id {uuid}.

  • Status 400

    • Error message.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • An OAuth Client with name “{name}” does not exist.

    • An OAuth Client with id "{uuid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Modify an OAuth Client: XML and JSON Examples 


XML

JSON

Example Request
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthClient retainSysIds="true">
    <clientId>client_id</clientId>
    <clientSecret>client_secret</clientSecret>
    <clusterRedirectUrls>
        <clusterRedirectUrl>
            <clusterNode>node1:8080-uc</clusterNode>
           <redirectUrl>http://localhost:8080/uc/oauth2/callback</redirectUrl>
        </clusterRedirectUrl>
    </clusterRedirectUrls>
    <description>description</description>
    <name>Google</name>
    <opswiseGroups/>
    <provider>Google</provider>
    <scopes>
        <scope>https://mail.google.com</scope>
    </scopes>
    <sysId>239119555c2c427f8f5b29faeecfdc27</sysId>
</oauthClient>
 JSON
{
    "clientId": "client_id",
    "clientSecret": "client_secret",
    "clusterRedirectUrls": [
        {
          "clusterNode": "node1:8080-uc",
          "redirectUrl":"htttp://localhost:8080/uc/oauth2/callback"
        }
    ],
    "description": "description",
    "name": "Google",
    "opswiseGroups": [],
    "provider": "Google",
    "retainSysIds": true,
    "scopes": [
        "https://mail.google.com"
    ],
    "sysId": "239119555c2c427f8f5b29faeecfdc27"
}

Read an OAuth Client


 Description

URI

http://host_name/uc/resources/oauthclient

HTTP Method

GET

Description

Retrieves information for a specific OAuth Client.

Example URI

http://localhost:8080/uc/resources/oauthclient?oauthclientname=testOAuthClient

Authentication

HTTP Basic

Produces Content-Type

application/xml, application/json

Consumes Content-Type

n/a

Example Responses

  • Status 200

    • See Example Response section below.

  • Status 404

    • An OAuth Client with name “{name}” does not exist.

    • An OAuth Client with id "{uuid}" does not exist.

Read an OAuth Client: Query Parameters

The following request parameters will be needed for the service.

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

oauthclientname



N/A

Name used within the Controller to identify the OAuth Client.

String; URI parameter

Y (unless oauthclientid is specified)

oauthclientid

oauthclientid



N/A

ID used within the Controller to identify the OAuth Client.

String; URI parameter

Y (unless oauthclientname is specified)

oauthclientname

Read an OAuth Client: XML and JSON Examples 


XML

JSON

Example Response
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthClient exportReleaseLevel="7.3.0.0" exportTable="ops_oauth_client" retainSysIds="true" version="5">
    <authorizationEndpoint>https://accounts.google.com/o/oauth2/v2/auth</authorizationEndpoint>
    <clientId>client_id</clientId>
    <clusterRedirectUrls>
        <clusterRedirectUrl>
            <clusterNode>node1:8080-uc</clusterNode>
            <redirectUrl>http://localhost:8180/uc/oauth2/callback</redirectUrl>
        </clusterRedirectUrl>
    </clusterRedirectUrls>
    <description>description</description>
    <name>Google</name>
    <opswiseGroups/>
    <provider>Google</provider>
    <scopes>
        <scope>https://mail.google.com</scope>
    </scopes>
    <sysId>239119555c2c427f8f5b29faeecfdc27</sysId>
    <tokenEndpoint>https://oauth2.googleapis.com/token</tokenEndpoint>
</oauthClient>
 JSON
{
    "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
    "clientId": "client_id",
    "clusterRedirectUrls": [
        {
            "clusterNode": "node1:8080-uc",
            "redirectUrl": "http://localhost:8080/uc/oauth2/callback"
        }
    ],
    "description": "description",
    "exportReleaseLevel": "7.3.0.0",
    "exportTable": "ops_oauth_client",
    "name": "Google",
    "opswiseGroups": [],
    "provider": "Google",
    "retainSysIds": true,
    "scopes": [
        "https://mail.google.com"
    ],
    "sysId": "239119555c2c427f8f5b29faeecfdc27",
    "tokenEndpoint": "https://oauth2.googleapis.com/token",
    "version": 5
}

Delete an OAuth Client


 Description

URI

http://host_name/uc/resources/oauthclient

HTTP Method

DELETE

Description

Deletes an OAuth Client.

Example URI

http://localhost:8080/uc/resources/oauthclient?oauthclientname=testOauthClient

Authentication

HTTP Basic

Produces Content-Type

n/a

Consumes Content-Type

n/a

Example Responses

  • Status 200

    • OAuth Client deleted successfully.

  • Status 404

    • An OAuth Client with name “{name}” does not exist.

    • An OAuth Client with id "{uuid}" does not exist.

Delete an OAuth Client: Query Parameters

The following request parameters will be needed for the service.

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

oauthclientname



N/A

Name used within the Controller to identify the OAuth Client.

String; URI parameter

Y (unless oauthclientid is specified)

oauthclientid

oauthclientid



N/A

ID used within the Controller to identify the OAuth Client.

String; URI parameter

Y (unless oauthclientname is specified)

oauthclientname

List OAuth Clients


 Description

URI

http://host_name/uc/resources/oauthclient/list

HTTP Method

GET

Description

Retrieves information for all OAuth Clients.

Example URI

http://localhost:8080/uc/resources/oauthclient/list

Authentication

HTTP Basic

Produces Content-Type

application/xml, application/json

Consumes Content-Type

n/a

Example Responses

  • Status 200

    • See Example Response section below.

List an OAuth Client: XML and JSON Examples 


XML

JSON

Example Response
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthClients>
    <oauthClient exportReleaseLevel="7.3.0.0" exportTable="ops_oauth_client" version="5">
        <authorizationEndpoint>https://accounts.google.com/o/oauth2/v2/auth</authorizationEndpoint>
        <clientId>client_id</clientId>
        <clusterRedirectUrls>
            <clusterRedirectUrl>
                <clusterNode>node1:8080-uc</clusterNode>
                <redirectUrl>http://localhost:8080/uc/oauth2/callback</redirectUrl>
            </clusterRedirectUrl>
        </clusterRedirectUrls>
        <description>description</description>
        <name>Google</name>
        <opswiseGroups/>
        <provider>Google</provider>
        <scopes>
            <scope>https://mail.google.com</scope>
        </scopes>
        <sysId>239119555c2c427f8f5b29faeecfdc27</sysId>
        <tokenEndpoint>https://oauth2.googleapis.com/token</tokenEndpoint>
    </oauthClient>
</oauthClients>
 JSON
[
    {
        "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
        "clientId": "client_id",
        "clusterRedirectUrls": [
            {
                "clusterNode": "node1:8080-uc",
                "redirectUrl": "http://localhost:8080/uc/oauth2/callback"
            }
        ],
        "description": "description",
        "exportReleaseLevel": "7.3.0.0",
        "exportTable": "ops_oauth_client",
        "name": "Google",
        "opswiseGroups": [],
        "provider": "Google",
        "scopes": [
            "https://mail.google.com"
        ],
        "sysId": "239119555c2c427f8f5b29faeecfdc27",
        "tokenEndpoint": "https://oauth2.googleapis.com/token",
        "version": 5
    },
]