The OAuth user configuration information used by an OAuthUserCredential. More...
| Header | #include <Authentication/ |
| Since | Esri |
| Inherits | Esri |
Public Functions
| O | |
| O | |
| virtual | ~ |
| bool | can |
| Q | client |
| Q | culture() const |
| int | federated |
| bool | is |
| Q | portal |
| Q | redirect |
| std | refresh |
| Esri | refresh |
| Esri | user |
| bool | operator!=( |
| bool | operator==( |
Reimplemented Public Functions
| virtual Q | to |
Static Public Members
| Esri | from |
Detailed Description
The portal URL, client ID, and redirect URL are required to create an OAuthUserCredential. You can get the client ID and redirect URL by following the Create OAuth credentials for user authentication tutorial.
To configure the lifetime of the OAuthUserCredential set the refresh token expiration and exchange intervals.
You can configure the look and feel of the OAuth login page, displayed by an OAuth user credential, by setting isShowCancelButton or userInterfaceStyle, for example.
There are two OAuth experiences for authenticating with ArcGIS services: 1) an external out-of-process browser, and 2) an in-app embedded browser. These are described in detail below
External out-of-process browser
The "external out-of-process browser workflow" refers to an experience where once an authentication challenge is issued, the system's default browser will open up an OAuth login page, outside of the application. Once successfully authenticated, you will be prompted to return back to your application, and the token will be passed back to the application.
This is the recommended pattern, as it is the most secure. However, it is only supported on iOS and Android.
This pattern makes use of Qt's Network Authorization module. Ensure you have installed this optional module if you would like to use this pattern.
App setup
Apps that support an out-of-process browser experience will need to specify a redirect URI in a format similar to the following: "qt-maps-sdk-app:/oauth2/callback". This must match the redirect URI specified when registering your OAuth application in your portal.
Android apps must include the following in their app's manifest to declare an Intent.
<intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="qt-maps-sdk-app"/> </intent-filter>
iOS apps must include the following permission in their app's plist.
<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>qt-maps-sdk-app</string> </array> </dict> </array>
In-app embedded browser
The "in-app embedded browser" workflow refers to an experience where a browser web view is embedded in the application. Once an authentication challenge is issued, the embedded browser will display the OAuth login page directly inside of the app.
This workflow is recommended for desktop applications, where the external out-of-process workflow is not supported.
This pattern requires Qt's web engine. Ensure you have installed this optional module if you would like to use this pattern.
App setup
Apps that support an in-app embedded browser experience must specify the redirect URI as "urn:ietf:wg:oauth:2.0:oob". This must match the redirect URI specified when registering your OAuth application in your portal.
Member Function Documentation
OAuthUserConfiguration::OAuthUserConfiguration (const QUrl &portalUrl , const QString &clientId , const QString &redirectUri , QObject *parent = nullptr)
Creates an OAuth configuration with the specified parameters.
- portalUrl - The URL of the portal to authenticate with.
- clientId - A unique identifier associated with an application registered with the portal that assists with client/server OAuth authentication.
- redirectUri - The URI that the OAuth login page redirects to when authentication completes.
- parent - The optional parent QObject.
Note: The following defaults are used:
- culture - the current system locale/culture.
- refreshTokenExpirationInterval - The requested expiration interval (in minutes) for the refresh token. The max interval can be overridden by the portal administrator. The value `-1` returns the maximum refresh token expiration interval supported by the portal, which is usually set to ninety days. The portal administrator has the ability to decrease this maximum value. The value `0` returns the default refresh token expiration interval configured on the portal, typically two weeks. This default value may be affected if the portal administrator sets the maximum refresh token value (ninety days) to less than two weeks.
- refreshTokenExchangeInterval - The requested exchange interval (in minutes) for the OAuth refresh token. Use this to exchange a refresh token before it expires. This will limit the number of times a user will have to login because of expiring tokens. -
std::nullopt. - federatedTokenExpirationInterval - The requested expiration interval (in minutes) for federated tokens generated using the OAuth credential.
- showCancelButton - A Boolean value indicating whether to show "Cancel" button on the OAuth login page.
- userInterfaceStyle - Constants indicating the interface style for the OAuth login page.
- preferPrivateWebBrowserSession - A Boolean value indicating whether the OAuth login session should ask the browser for a private authentication session.
OAuthUserConfiguration::OAuthUserConfiguration (const QUrl &portalUrl , const QString &clientId , const QString &redirectUri , const QString &culture, const Esri::ArcGISRuntime::Authentication::OAuthRefreshTokenExpirationInterval &refreshTokenExpirationInterval , std::optional <int> refreshTokenExchangeInterval , int federatedTokenExpirationInterval , bool showCancelButton , Esri::ArcGISRuntime::Authentication::UserInterfaceStyle userInterfaceStyle , QObject *parent = nullptr)
Creates an OAuth configuration with the specified parameters.
- portalUrl - The URL of the portal to authenticate with.
- clientId - A unique identifier associated with an application registered with the portal that assists with client/server OAuth authentication.
- redirectUri - The URI that the OAuth login page redirects to when authentication completes.
- culture - The OAuth login page is displayed in the language specified by the given culture code.
- refreshTokenExpirationInterval - The requested expiration interval (in minutes) for the refresh token. The max interval can be overridden by the portal administrator. The value `-1` returns the maximum refresh token expiration interval supported by the portal, which is usually set to ninety days. The portal administrator has the ability to decrease this maximum value. The value `0` returns the default refresh token expiration interval configured on the portal, typically two weeks. This default value may be affected if the portal administrator sets the maximum refresh token value (ninety days) to less than two weeks.
- refreshTokenExchangeInterval - The requested exchange interval (in minutes) for the OAuth refresh token. Use this to exchange a refresh token before it expires. This will limit the number of times a user will have to login because of expiring tokens.
- federatedTokenExpirationInterval - The requested expiration interval (in minutes) for federated tokens generated using the OAuth credential.
- showCancelButton - A Boolean value indicating whether to show "Cancel" button on the OAuth login page.
- userInterfaceStyle - Constants indicating the interface style for the OAuth login page.
- parent - The optional parent QObject.
[override virtual noexcept] OAuthUserConfiguration::~OAuthUserConfiguration ()
Destructor.
bool OAuthUserConfiguration::canBeUsedForUrl (const QUrl &url) const
Returns if this configuration can be used for the given URL.
- url - The URL to check.
QString OAuthUserConfiguration::clientId () const
Returns a unique identifier associated with an application registered with the portal that assists with client/server OAuth authentication.
QString OAuthUserConfiguration::culture() const
Returns the OAuth login page is displayed in the language specified by the given culture code.
If not explicitly set, the culture used by the device/machine is used. If the culture is not supported by the portal then OAuth login page will be displayed in the language corresponding to culture specified in the portal/organization settings. The format for culture code is based on a language code and a country code separated by a dash. Example: "en-US".
int OAuthUserConfiguration::federatedTokenExpirationInterval () const
Returns the requested expiration interval (in minutes) for federated tokens generated using the OAuth credential.
[static] Esri::ArcGISRuntime::Authentication::OAuthUserConfiguration *OAuthUserConfiguration::fromJson (const QString &json, QObject *parent)
Convert a JSON string to an object.
- json - The JSON string.
- parent - The optional parent QObject.
bool OAuthUserConfiguration::isShowCancelButton () const
Returns a boolean value indicating whether to show the "Cancel" button on the OAuth login page.
QUrl OAuthUserConfiguration::portalUrl () const
Returns the URL of the portal to authenticate with.
QString OAuthUserConfiguration::redirectUri () const
Returns the URI that the OAuth login page will redirect to when authentication completes.
std::optional <int> OAuthUserConfiguration::refreshTokenExchangeInterval () const
Returns the requested exchange interval (in minutes) for the OAuth refresh token. Use this to exchange a refresh token before it expires. This will limit the number of times a user will have to login because of expiring tokens.
If the exchange interval is set to std::nullopt, then the refresh token will never be exchanged and will eventually expire, causing the user to have to log in again. Note that 0 or any negative number will be treated as std::nullopt.
To have any affect, this should be set to a value less than the refreshTokenExpirationInterval. Setting it to a value greater than the refreshTokenExpirationInterval will have the same effect as setting this to std::nullopt.
It is recommended to keep this interval as low as possible because long lived refresh tokens may increase the security risk.
See also refreshTokenExpirationInterval.
Esri::ArcGISRuntime::Authentication::OAuthRefreshTokenExpirationInterval OAuthUserConfiguration::refreshTokenExpirationInterval () const
Returns the requested expiration interval (in minutes) for the refresh token.
The maximum interval can be overridden by the portal administrator.
The value `-1` returns the maximum refresh token expiration interval supported by the portal, which is usually set to ninety days. The portal administrator has the ability to decrease this maximum value. - The value `0` returns the default refresh token expiration interval configured on the portal, typically two weeks. This default value may be affected if the portal administrator sets the maximum refresh token value (ninety days) to less than two weeks.
See also refreshTokenExchangeInterval and RefreshTokenExpirationInterval.
[override virtual] QString OAuthUserConfiguration::toJson () const
Reimplements: JsonSerializable::toJson() const.
Returns convert an object to JSON string.
Esri::ArcGISRuntime::Authentication::UserInterfaceStyle OAuthUserConfiguration::userInterfaceStyle () const
Returns constants indicating the interface style for the OAuth login page.
The default is UserInterfaceStyle::Unspecified.
bool OAuthUserConfiguration::operator!=(Esri::ArcGISRuntime::Authentication::OAuthUserConfiguration *other) const
Tests and returns true if the two OAuthUserConfiguration objects are not equal.
- other - The configuration to compare to.
bool OAuthUserConfiguration::operator==(Esri::ArcGISRuntime::Authentication::OAuthUserConfiguration *other) const
Tests and returns true if the two OAuthUserConfiguration objects are equal.
- other - The configuration to compare to.