cui.js "Authentication" Calls

covAuth(options)
Obtain a JWT access token for the specified Covisint Application.

The Covisint Application-specific additional service URL's are retrieved and cached, and a call is then made to the Application's login URL.

Note. The App code must call handleCovAuthResponse() to complete the authentication process. Then, the received token will be used for JWT authentication in all subsequent API calls.
options.appRedirect
String

Optional.
(Defaults to the URL of the App, at the time of the covAuth() call).

A state holder for the App, the value of which is cached and then available to the App after successful authentication (via the getAuthInfo() call). This is useful in scenario's where the covAuth() call occurs from multiple pages, and a single authRedirect route is used for handling post-authentication logic, as well as restoring the App user's state, after authentication.
options.authRedirect
String

Optional.
(Defaults to the URL of the App, at the time of the covAuth() call).

The URL that the Covisint Application's login handler will invoke after performing the login. This is typically a URL back into the existing App.
options.isIot
Boolean

Optional.
(Defaults to false).

If the options.originUri is iot-based, this must be set to true.
options.originUri
String

Optional.
(Defaults to the hostname of the App, at the time of the covAuth() call).

The identifier of the Covisint Application. The Origin URI is obtained when the Application is initially configured.
options.popup
Boolean

Optional.
If specified, causes the authentication process to occur in a popup, rather than in the existing browser window/tab.
Returns
Promise

If options.popup, resolves with the value of getAuthInfo(). Otherwise neither resolves or rejects since the resulting action is a redirect back into a different part of the App (as specified via the options.appRedirect property).
covAuthInfo(options)
Call the Covisint Solution Service to get Application-specific URLs to various additional service endpoints.

Note. This call is automatically invoked as part of the covAuth() call.
options.originUri
String

Optional.
(Defaults to the hostname of the App, at the time of the covAuth() call).

An identifier for the Covisint Application. Obtained when the Application is initially configured.
options.isIot
Boolean

Optional.
(Defaults to false).

If the Covisint Application's originUri is iot-based, this must be set to true.
Returns
Promise

Resolves with the object that specifies the Application's URLs to additional services. If the object's properties are empty, then rejects with the object of blank properties.
covLogout(options)
Logout from a JWT-based session.

The token is dropped from the cache, the JWT token is invalidated, and the Covisint Application's logout URL is invoked.
options.redirect
Boolean

Optional.
(Defaults to the URL of the App, at the time of the covLogout() call).

The URL that the Covisint Application's logout handler will invoke after performing the logout. This is typically a URL back into the existing App.
Returns
Promise

Neither resolves or rejects since the resulting action is a redirect back into a different part of the App (as specified via the options.redirect property).
doSysAuth(options)
Obtain a system-level access token for the specified Covisint Application.

The received token will be used for bearer-type authentication in all subsequent API calls.

The received token will be AUTOMATICALLY refreshed.
options.clientId
String

The client identifier of the Covisint Application. Obtained when the Application is initially configured.
options.clientSecret
String

The client secret of the Covisint Application. Obtained when the Application is initially configured.
Returns
Promise

If authentication was successful, resolves with the value of the getToken(). Otherwise, rejects an error object.
doThreeLeggedOAuth(options)
Start an interactive 3-legged OAuth login in a popup window.

The user will first be prompted to log into the Covisint Application connected to the supplied clientId. Upon successful login, the user will then be prompted for consent to allow the App to use information obtained from the Covisint Person to which they authenticated.

The App code must call handleAuthResponse() to complete the authentication process. Then, the received token will be used for bearer-type authentication in all subsequent API calls.
options.clientId
String

The client identifier of the Covisint Application.
options.scope
String

Optional.
(Defaults to 'all').

The space-delimited authorization scope(s) being requested. The values are shown in the authorization form that is presented to the user for consent.
Returns
Promise

If authentication is successful, resolves with the value of getToken(). Otherwise, rejects with no value.
getCovAuthInfo()
Get the cached Application-specific URL object (obtained via an earlier covAuth() or covAuthInfo() call).
Returns
Object

An object that specifies the Application's URLs to additional services. ALSO, includes appRedirect values that were set via earlier covAuth() calls.
getToken()
Get the cached bearer-token.
Returns
String

The bearer-token value. This value is suitable to be passed as a paremeter when the token is being explicitly introspected, refreshed, or revoked.
handleAuthResponse()
Watch for the receipt of the 3-legged OAuth token, and cache it upon arrival.

This method must be included in the same page that is registered as the Covisint Application's oauth.configuration.redirectUri. This can be set via the updateClientApplication() call from the Admin API.
Returns
Promise

If token was received, resolves with the value of the received token. Else, if token exists, resolves with the value of the existing token. Otherwise, neither resolves or rejects.
handleCovAuthResponse(options)
Watch for the receipt of the JWT login token, and cache it upon arrival.

This method must be included in the page that corresponds to the option.authRedirect value specified with the covAuth() call.
options.selfRedirect
Boolean

Optional.
(Defaults to false).

If true specifies that during resolution, no redirection will occur. This allows App's with routing frameworks (e.g. AngularJs) to perform the redirection within the constructs of that framework.
Returns
Promise

If token was received, resolves with the value of the getAuthInfo() AND redirects to the value of appRedirect as specified in the covAuth() call. Else, if token already exists, resolves with the value of getAuthInfo(). Otherwise, neither resolves or rejects.
setAuthGiveUpHandler(fn)
Register the App method to be invoked whenever a 401 error is repeatedly encountered (more than twice consecutively).

This is optional feature for user-token-based authentication scenarios (i.e. JWT, OAUTH) that make use of the setAuthHandler() call. Having a registered give up handler allows the App to gain control during a situation where API login services are, for whatever reason, unavailable.
fn
Function

The App-defined function.
Returns
Function

The passed-in function
setAuthHandler(fn)
Register the App method to be invoked whenever a 401 error is encountered.
fn
Function

The App-defined function, which minimally invokes covAuth() or doThreeLeggedOAuth().

This is required in user-token authentication scenarios (JWT, OAUTH), where API access can lapse or expire.
Returns
Function

The passed-in function