OAuth Single Sign-On Web Services

Owned by Stonebranch (Deactivated)
Last updated: Aug 16, 2024
8 min read

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.

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

XMLJSON
 XML
<?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>
 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.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


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 

XMLJSON
 XML
<?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>
 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.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

PropertyUI Field NameDescriptionSpecificationsRequired

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