Overview

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

Read OAuth Single Sign-On Settings
Update OAuth Single Sign-On Settings

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

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

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthSettings exportReleaseLevel="7.8.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>
    <portalApiScopes/>
    <portalClientId>0oa22oz08...9O50h8</portalClientId>
    <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>

JSON

{
    "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.8.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,
    "portalApiScopes": [],
    "portalClientId": "0oa22oz08...9O50h8",
    "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

	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

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oauthSettings exportReleaseLevel="7.8.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>
    <portalApiScopes/>
    <portalClientId>0oa22oz08...9O50h8</portalClientId>
    <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>

JSON

{
    "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.8.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,
    "portalApiScopes": [],
    "portalClientId": "0oa22oz08...9O50h8",
    "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 <userProvisioning/> <userProvisioning> <userProvisioningOption>Web Browser Access</userProvisioningOption> <userProvisioningOption>Web Service Access</userProvisioningOption> </userProvisioning> JSON "userProvisioning": [] "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 <scopes> <scope>profile</scope> <scope>openid</scope> <scope>email</scope> </scopes> JSON "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 <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 "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	The Name of a multi-valued attribute from the Access or ID Token containing the Group Names the user is a member of.		N
`portalClientId`	Portal Client Id	Client identifier for the Universal Portal Single Page Application required for OAuth flows.	XML <portalApiScopes> <scope>profile</scope> <scope>openid</scope> <scope>email</scope> </scopes> JSON "portalApiScopes": [ "profile", "openid", "email" ]	N
`portalApiScopes`	Portal API Scopes	Optionally, specifies the scopes required when requesting an Access Token for the Universal Controller Web Application APIs. For example, if the Universal Portal SPA needs to specify a custom scope `api://{client-id}/resources` in addition to `openid` and `profile` when requesting an Access Token for the Universal Controller Web Application APIs, you would specify the following. api://{client-id}/resources openid profile If left unspecified, the Universal Portal SPA will use the Scopes.		N

Browser not supported