Authentication#

Functions#

void omniClientAuthenticationCancel(uint32_t authHandle): Call this to cancel the current authentication process.
void omniClientReconnect(const char *url): Attempt to reconnect, even if the previous connection attempt failed.
uint32_t omniClientRegisterAuthCallback(void *userData, OmniClientAuthCallback callback): Register a callback to provide authentication credentials.
uint32_t omniClientRegisterAuthDeviceFlowCallback(void *userData, OmniClientAuthDeviceFlowCallback callback): Register a function to be called when authenticating using "Device Flow".
uint32_t omniClientRegisterStorageAuthCallback(void *userData, OmniClientStorageAuthCallback callback): Register a function to be called when authenticating to an OmniStorage service.
void omniClientSetAuthenticationMessageBoxCallback(void *userData, OmniClientAuthenticationMessageBoxCallback callback): Set a callback which is called instead of showing the "Please sign in using your browser" dialog.
bool omniClientSetStorageAccessToken(uint32_t authHandle, char const *accessToken): Provide or refresh an access token for an OmniStorage server.
void omniClientSignOut(char const *url): Immediately disconnect from the server specified by this URL.

Structs#

OmniClientAuthDeviceFlowParams: This struct contains data provided to the "Device Flow" authentication callback.
OmniClientCredentials: Credentials to sign in with.

Typedefs#

OmniClientAuthCallback: This allows you to provide credentials used to sign in to a server.
OmniClientAuthDeviceFlowCallback: This is called when connecting to a server using "Device Flow" authentication.
OmniClientAuthenticationMessageBoxCallback: This is called when the library needs to continue authentication in a web browser.
OmniClientStorageAuthCallback: This is called when connecting to an OmniStorage service that requires authentication.

Functions#

void omniClientAuthenticationCancel(uint32_t authHandle)#

Call this to cancel the current authentication process.

This should only be used if the user clicks “Cancel” in conjection with omniClientSetAuthenticationMessageBoxCallback or omniClientRegisterAuthDeviceFlowCallback or omniClientRegisterStorageAuthCallback

authHandle is the same value passed to the callbacks.

Parameters:: authHandle – The authentication handle to cancel

void omniClientReconnect(const char *url)#

Attempt to reconnect, even if the previous connection attempt failed.

Automatic connection does not normally try again after failure you can call this function to force a retry

Parameters:: url – The URL of the server to reconnect to

uint32_t omniClientRegisterAuthCallback( void *userData, OmniClientAuthCallback callback, )#

Register a callback to provide authentication credentials.

More than one callback can be registered at the same time, they will be called newest-to-oldest until one of them returns ‘true’ indicating that it wants to handle the request Returns a handle that you provide to omniClientUnregisterCallback

The authentication callback receives the “prefix” of the server it’s trying to connect to, which could be of the form “omniverse://server:port” “http://server” “file://server” etc.. You can use omniClientBreakUrl to Parse the prefix into scheme, host, and port. Return false to fall back to the default credentials (for example because this is not a server you care about) Return true if you have filled in the credentials Either: Set credentials->abort to true to stop the sign-in process OR set credentials->token OR set credentials->username and credentials->password

Parameters:

userData – User data passed to the callback
callback – The callback function to register

Returns:

A handle that you can use with omniClientUnregisterCallback

uint32_t omniClientRegisterAuthDeviceFlowCallback( void *userData, OmniClientAuthDeviceFlowCallback callback, )#

Register a function to be called when authenticating using “Device Flow”.

If any device flow auth callbacks are registered, we will prefer the device flow auth instead of launching a web browser.

Parameters:

userData – User data passed to the callback
callback – The callback function to register

Returns:

A handle that you can use with omniClientUnregisterCallback

uint32_t omniClientRegisterStorageAuthCallback( void *userData, OmniClientStorageAuthCallback callback, )#

Register a function to be called when authenticating to an OmniStorage service.

Multiple callbacks can be registered, and all of them will be called for each authentication request until one returns true. A callback should return true if it will handle the authentication for the given server, and false otherwise. This allows different components to handle authentication for different servers (e.g., by checking the server parameter and returning true only if it matches the servers they manage).

If all registered callbacks return false (or if no callbacks are registered), the library will fall back to the default behavior of automatically launching a web browser and using cached tokens.

Parameters:

userData – User data passed to the callback
callback – The callback function to register

Returns:

A handle that you can use with omniClientUnregisterCallback

void omniClientSetAuthenticationMessageBoxCallback( void *userData, OmniClientAuthenticationMessageBoxCallback callback, )#

Set a callback which is called instead of showing the “Please sign in using your browser” dialog.

Parameters:

userData – User data passed to the callback
callback – The callback function to register, or nullptr to clear the callback

bool omniClientSetStorageAccessToken( uint32_t authHandle, char const *accessToken, )#

Provide or refresh an access token for an OmniStorage server.

This can be called in two scenarios:

After receiving a OmniClientStorageAuthCallback to provide the initial access token
At any time to proactively refresh an expiring token (tokens typically expire every 30 minutes)

The application is responsible for monitoring token expiration and calling this function with a fresh token before the current one expires.

Parameters:

authHandle – The authentication handle that was provided in the OmniClientStorageAuthCallback
accessToken – The access token obtained from the OAuth flow

Returns:

true if the token was successfully delivered to a waiting authentication handler, false if no handler was found for this authHandle

void omniClientSignOut(char const *url)#

Immediately disconnect from the server specified by this URL.

Any outstanding requests will call their callbacks with eOmniClientResult_ErrorConnection Additionally, clear the saved authentication token so future requests to this server will trigger re-authentication

Parameters:: url – The URL of the server to sign out from

Typedefs#

typedef bool (*OmniClientAuthCallback)(void *userData, char const *prefix, struct OmniClientCredentials *credentials)#: This allows you to provide credentials used to sign in to a server.

typedef void (*OmniClientAuthDeviceFlowCallback)(void *userData, uint32_t authHandle, struct OmniClientAuthDeviceFlowParams const *params)#

This is called when connecting to a server using “Device Flow” authentication.

authHandle is a handle that can be used to cancel authentication with omniClientAuthenticationCancel. params contains information about this auth attempt that you should show to the user. If params is null that means this auth attempt is finished (either successfully or not, you can use the connection status callback to determine which). You can use authHandle to determine which attempt was finished, since there may be multiple auth attempts in-flight at the same time (if trying to connect to multiple servers simultaneously).

typedef void (*OmniClientAuthenticationMessageBoxCallback)(void *userData, bool show, const char *server, uint32_t authHandle)#: This is called when the library needs to continue authentication in a web browser.

typedef bool (*OmniClientStorageAuthCallback)(void *userData, uint32_t authHandle, char const *server)#

This is called when connecting to an OmniStorage service that requires authentication.

The application should perform the OAuth flow to obtain an access token, then call omniClientSetStorageAccessToken with the obtained access token. If the authentication cannot be completed, call omniClientAuthenticationCancel instead.

The application is also responsible for monitoring token expiration and proactively refreshing tokens by calling omniClientSetStorageAccessToken with the same server URL and a fresh access token.

To retrieve the authentication configuration (OAuth endpoints, client ID, etc.), make an HTTP GET request to {server}/api/auth-config

Param userData:: User data passed to the callback
Param authHandle:: A handle that uniquely identifies this authentication request. Pass this to omniClientAuthenticationCancel if you need to cancel the authentication
Param server:: The server URL that requires authentication. Use this with omniClientSetStorageAccessToken to provide tokens
Return:: true if this callback will handle the authentication for this server, false to let another callback or the library handle it