Panel

Table of Contents

Overview

Universal Controller supports the following RESTful-based web services for OAuth Single Sign-On Settings, which are listed alphabetically on this page.

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

Anchor

	read
	read

Read OAuth Single Sign-On Settings

	Description
URI	http://host_name/uc/resources/oauthsettings
HTTP Method	GET
Description	Read the OAuth Single Sign-On Settings.
Example URI	http://localhost:8080/uc/resources/oauthsettings
Authentication	Required
Produces Content-Type	application/xml, application/json
Consumes Content-Type	N/A
Example Responses	Status 200 Status 403 Operation prohibited due to security constraints.

Read OAuth Single Sign-On Settings: XML and JSON Responses

XML

JSON

Expand

title	XML

Code Block

language	text

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthSettings exportReleaseLevel="7.7.0.0" exportTable="ops_oauth_settings">
    <attrActive />
    <attrDepartment />
    <attrEmail>email</attrEmail>
    <attrFirstName>given_name</attrFirstName>
    <attrGroups>groups</attrGroups>
    <attrHomePhone />
    <attrLastName>family_name</attrLastName>
    <attrManager />
    <attrMiddleName />
    <attrMobilePhone />
    <attrPhone />
    <attrTitle />
    <clientId>0oa22oyww...NIS0h8</clientId>
    <clusterBaseRedirectUrls>
        <clusterBaseRedirectUrl>
            <baseRedirectUrl>http://example.com:8080/uc</baseRedirectUrl>
            <clusterNode>example.com:8080-uc</clusterNode>
        </clusterBaseRedirectUrl>
    </clusterBaseRedirectUrls>
    <issuerUri>https://{accountId}.oktapreview.com/oauth2/default</issuerUri>
    <jwtAudienceClaimValue>api://default</jwtAudienceClaimValue>
    <jwtJwkSetUri />
    <opaqueIntrospectionUri />
    <pkce>true</pkce>
    <scopes>
        <scope>openid</scope>
        <scope>profile</scope>
        <scope>email</scope>
    </scopes>
    <singleSignOn>true</singleSignOn>
    <sysId>78c1fcdd9df446fb82c0bd74bfb0697e</sysId>
    <tokenValidation>JWT</tokenValidation>
    <userNameClaimName>uc_username</userNameClaimName>
    <userProvisioning>
        <userProvisioningOption>Web Browser Access</userProvisioningOption>
        <userProvisioningOption>Web Service Access</userProvisioningOption>
    </userProvisioning>
</oauthSettings>

Expand

title	JSON

Code Block

language	text

{
    "attrActive": null,
    "attrDepartment": null,
    "attrEmail": "email",
    "attrFirstName": "given_name",
    "attrGroups": "groups",
    "attrHomePhone": null,
    "attrLastName": "family_name",
    "attrManager": null,
    "attrMiddleName": null,
    "attrMobilePhone": null,
    "attrPhone": null,
    "attrTitle": null,
    "clientId": "0oa22oyww...NIS0h8",
    "clusterBaseRedirectUrls": [
        {
            "baseRedirectUrl": "http://example.com:8080/uc",
            "clusterNode": "example.com:8080-uc"
        }
    ],
    "exportReleaseLevel": "7.7.0.0",
    "exportTable": "ops_oauth_settings",
    "issuerUri": "https://{accountId}.oktapreview.com/oauth2/default",
    "jwtAudienceClaimValue": "api://default",
    "jwtJwkSetUri": null,
    "opaqueIntrospectionUri": "https://{accountId}.oktapreview.com/oauth2/default",
    "pkce": true,
    "scopes": [
        "openid",
        "profile",
        "email"
    ],
    "singleSignOn": true,
    "sysId": "78c1fcdd9df446fb82c0bd74bfb0697e",
    "tokenValidation": "JWT",
    "userNameClaimName": "uc_username",
    "userProvisioning": [
        "Web Browser Access",
        "Web Service Access"
    ]
}

Anchor

	update
	update

Update OAuth Single Sign-On Settings

	Description
URI	http://host_name/uc/resources/oauthsettings
HTTP Method	PUT
Description	Update the OAuth Single Sign-On Settings.
Example URI	http://localhost:8080/uc/resources/oauthsettings
Authentication	Required
Produces Content-Type	text/plain
Consumes Content-Type	application/xml, application/json
Example Responses	Status 200 Successfully updated the OAuth Single Sign-On Settings with id 78c1fcdd9df446fb82c0bd74bfb0697e.

Update OAuth Single Sign-On Settings: XML and JSON Requests

XML

JSON

Expand

title	XML

Code Block

language	text

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthSettings exportReleaseLevel="7.7.0.0" exportTable="ops_oauth_settings">
    <attrActive />
    <attrDepartment />
    <attrEmail>email</attrEmail>
    <attrFirstName>given_name</attrFirstName>
    <attrGroups>groups</attrGroups>
    <attrHomePhone />
    <attrLastName>family_name</attrLastName>
    <attrManager />
    <attrMiddleName />
    <attrMobilePhone />
    <attrPhone />
    <attrTitle />
    <clientId>0oa22oyww...NIS0h8</clientId>
    <clusterBaseRedirectUrls>
        <clusterBaseRedirectUrl>
            <baseRedirectUrl>http://example.com:8080/uc</baseRedirectUrl>
            <clusterNode>example.com:8080-uc</clusterNode>
        </clusterBaseRedirectUrl>
    </clusterBaseRedirectUrls>
    <issuerUri>https://{accountId}.oktapreview.com/oauth2/default</issuerUri>
    <jwtAudienceClaimValue>api://default</jwtAudienceClaimValue>
    <jwtJwkSetUri />
    <opaqueIntrospectionUri />
    <pkce>true</pkce>
    <scopes>
        <scope>openid</scope>
        <scope>profile</scope>
        <scope>email</scope>
    </scopes>
    <singleSignOn>true</singleSignOn>
    <sysId>78c1fcdd9df446fb82c0bd74bfb0697e</sysId>
    <tokenValidation>JWT</tokenValidation>
    <userNameClaimName>uc_username</userNameClaimName>
    <userProvisioning>
        <userProvisioningOption>Web Browser Access</userProvisioningOption>
        <userProvisioningOption>Web Service Access</userProvisioningOption>
    </userProvisioning>
</oauthSettings>

Expand

title	JSON

Code Block

language	text

{
    "attrActive": null,
    "attrDepartment": null,
    "attrEmail": "email",
    "attrFirstName": "given_name",
    "attrGroups": "groups",
    "attrHomePhone": null,
    "attrLastName": "family_name",
    "attrManager": null,
    "attrMiddleName": null,
    "attrMobilePhone": null,
    "attrPhone": null,
    "attrTitle": null,
    "clientId": "0oa22oyww...NIS0h8",
    "clusterBaseRedirectUrls": [
        {
            "baseRedirectUrl": "http://example.com:8080/uc",
            "clusterNode": "example.com:8080-uc"
        }
    ],
    "exportReleaseLevel": "7.7.0.0",
    "exportTable": "ops_oauth_settings",
    "issuerUri": "https://{accountId}.oktapreview.com/oauth2/default",
    "jwtAudienceClaimValue": "api://default",
    "jwtJwkSetUri": null,
    "opaqueIntrospectionUri": "https://{accountId}.oktapreview.com/oauth2/default",
    "pkce": true,
    "scopes": [
        "openid",
        "profile",
        "email"
    ],
    "singleSignOn": true,
    "sysId": "78c1fcdd9df446fb82c0bd74bfb0697e",
    "tokenValidation": "JWT",
    "userNameClaimName": "uc_username",
    "userProvisioning": [
        "Web Browser Access",
        "Web Service Access"
    ]
}

Update OAuth Single Sign-On Settings: Payload Properties

Property UI Field Name Description Specifications Required

singleSignOn

OAuth Single Sign-On

If true, turns on OAuth Single Sign-On.

If false, turns off OAuth Single Sign-On.

Boolean; Valid values: true/false. Default is false.

N

userProvisioning

User Provisioning

Turn on or off the provisioning of users through Access or ID Token attributes.

Select the application access method(s) you want User Provisioning to be applied.

Valid values (case-insensitive):

As String = Web Browser Access, As Value = 1
As String = Web Service Access, As Value = 2

XML

Code Block

language	text

<userProvisioning/>

Code Block

language	text

<userProvisioning>
    <userProvisioningOption>Web Browser Access</userProvisioningOption>
    <userProvisioningOption>Web Service Access</userProvisioningOption>
</userProvisioning>

JSON

Code Block

language	text

"userProvisioning": []

Code Block

language	text

"userProvisioning": [
    "Web Browser Access",
    "Web Service Access"
]

N

issuerUri

Issuer URI

Universal Controller uses the Issuer URI for discovery of the OpenID Connect / OAuth 2.0 protocol endpoints for authenticating users.

One of the following must be a supported endpoint for the authorization server, referred to as a Provider Configuration endpoint or a Authorization Server Metadata endpoint.

{Issuer URI}/.well-known/openid-configuration

{Issuer URI Host}/.well-known/openid-configuration/{Issuer URI Path}

{Issuer URI Host}/.well-known/oauth-authorization-server/{Issuer URI Path}

Must be a valid URL beginning with http://, or https:// and contain no spaces.

Y

(if singleSignOn is true)

clientId

Client Id

Client identifier for the Universal Controller Web Application required for OAuth flows.

Y

(if singleSignOn is true)

clientSecret

Client Secret

Client secret used for client authentication with the authorization server.

The clientSecret is not returned in the GET response payload.

Y

(if singleSignOn is true)

scopes

Scopes

Specify a comma-delimited list of OAuth scopes. If left unspecified will default to "openid".

XML

Code Block

language	text

<scopes>
    <scope>profile</scope>
    <scope>openid</scope>
    <scope>email</scope>
</scopes>

JSON

Code Block

language	text

"scopes": [
    "profile",
    "openid",
    "email"
]

N

userNameClaimName

User Id (Username) Claim Name

Specifies the name of a specific claim / attribute to identify the Universal Controller User Id (Username).

If left unspecified will default to the Subject identifier (sub).

N

pkce

Proof Key for Code Exchange (PKCE)

Authorization Code grant type requires PKCE as additional verification.

Boolean; Valid values: true/false. Default is false.

N

clusterBaseRedirectUrls

Cluster Node Base Redirect URLs

Cluster Node Base Redirect URLs are used to construct the sign-in redirection endpoint for each Cluster Node and are specified as a URL with protocol, server, port, and context path

scheme://server:port/contextPath

If not specified, defaults to values from the request using the Host header value, if any, or the resolved server name (or server IP address) and server port the client connection was accepted on.

It is recommended that you specify the Base Redirect URL for each Cluster Node rather than rely on the Host header value for redirection endpoint resolution.

The fully qualified sign-in redirection endpoint for each Cluster Node will be:

{Cluster Node Base Redirect URL}/login/oauth2/code/default

Each Cluster Node's fully qualified sign-in redirection endpoint must be added to your registered application in the authorization server.

XML

Code Block

language	text

<clusterBaseRedirectUrls>
    <clusterBaseRedirectUrl>
        <baseRedirectUrl>http://example.com:8080/uc</baseRedirectUrl>
        <clusterNode>node1:8080-uc</clusterNode>
    </clusterBaseRedirectUrl>
    <clusterBaseRedirectUrl>
        <baseRedirectUrl>http://example.com:8080/uc</baseRedirectUrl>
        <clusterNode>node2:8080-uc</clusterNode>
    </clusterBaseRedirectUrl>
</clusterBaseRedirectUrls>

JSON

Code Block

language	text

"clusterBaseRedirectUrls": [
    {
        "baseRedirectUrl": "http://example.com:8080/uc",
        "clusterNode": "node1:8080-uc"
    },
    {
        "baseRedirectUrl": "http://example.com:8080/uc",
        "clusterNode": "node2:8080-uc"
    }
]

baseRedirectUrl must be a valid URL beginning with http://, or https:// and contain no spaces.

baseRedirectUrl cannot have a trailing '/' character.

clusterNode must be a valid Cluster Node Node Id.

N

tokenValidation

OAuth Bearer Token Validation

Choose the type of OAuth2 Bearer Token authentication supported for Universal Controller Web Service API endpoints.

If None, then only Basic and Personal Access Token authentication are supported.

Valid values (case-insensitive):

As String = None, As Value = 0 (Default)
As String = Opaque Token, As Value = 1
As String = JWT, As Value = 2

N

opaqueIntrospectionUri

Introspection URI

The introspection endpoint URI.

Must be a valid URL beginning with http://, or https:// and contain no spaces.

Y

(if singleSignOn is true and tokenValidation is Opaque Token)

jwtJwkSetUri

JWK Set URI

Specifies a JSON Web Key (JWK) endpoint that contains public keys used for Access and ID Token verification.

If left unspecified, Universal Controller will use the Issuer URI to query the Provider Configuration or Authorization Server Metadata endpoint for the JWK Set URI.

Must be a valid URL beginning with http://, or https:// and contain no spaces.

N

jwtAudienceClaimValue

Audience Claim Value

Specification of the expected audience claim value so the Universal Controller can validate the Token audience (aud) matches.

N

attrFirstName

First Name

The Name of an attribute from the Access or ID Token containing the user's First Name.

Y

(if singleSignOn is true and userProvisioning is true)

attrMiddleName

Middle Name

The Name of an attribute from the Access or ID Token containing the user's Middle Name.

N

attrLastName

Last Name

The Name of an attribute from the Access or ID Token containing the user's Last Name.

N

attrEmail

Email

The Name of an attribute from the Access or ID Token containing the user's Email.

N

attrTitle

Title

The Name of an attribute from the Access or ID Token containing the user's Title.

N

attrDepartment

Department

The Name of an attribute from the Access or ID Token containing the user's Department.

N

attrManager

Manager

The Name of an attribute from the Access or ID Token containing the user's Manager Name.

N

attrBusinessPhone

Business Phone

The Name of an attribute from the Access or ID Token containing the user's Business Phone.

N

attrMobilePhone

Mobile Phone

The Name of an attribute from the Access or ID Token containing the user's Mobile Phone.

N

attrHomePhone

Home Phone

The Name of an attribute from the Access or ID Token containing the user's Home Phone.

N

attrActive

Active

The Name of an attribute from the Access or ID Token containing the user's Active condition.

N

attrGroups

Groups

N

selfServiceClientId

Self Service Client Id

The Name of a multi-valued attribute from the Access or ID Token containing the Group Names the user is a member of.

N

Versions Compared

Old Version 1

New Version Current

Key

Overview

Read OAuth Single Sign-On Settings

Read OAuth Single Sign-On Settings: XML and JSON Responses

Update OAuth Single Sign-On Settings

Update OAuth Single Sign-On Settings: XML and JSON Requests

Update OAuth Single Sign-On Settings: Payload Properties

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Overview

Read OAuth Single Sign-On Settings

Read OAuth Single Sign-On Settings: XML and JSON Responses

Update OAuth Single Sign-On Settings

Update OAuth Single Sign-On Settings: XML and JSON Requests

Update OAuth Single Sign-On Settings: Payload Properties