@arcgis/core

import type { JSONSupport } from "../core/JSONSupport.js"; export interface OAuthInfoProperties extends Partial<Pick<OAuthInfo, "appId" | "authNamespace" | "expiration" | "flowType" | "forceUserId" | "locale" | "minTimeUntilExpiration" | "popup" | "popupCallbackUrl" | "popupWindowFeatures" | "portalUrl" | "preserveUrlHash" | "userId">> {} /** * This class contains information about an OAuth 2.0 configuration. Use it in combination with the * [IdentityManager](https://developers.arcgis.com/javascript/latest/references/core/identity/IdentityManager/) widget to aid in working with OAuth 2.0 authentication. * * One-step authentication has been superseded by the recommended two-step approach with [Proof Key for Code Exchange (PKCE)](https://oauth.net/2/pkce/). * * This update coincides with recommendations in the [OAuth 2.1](https://oauth.net/2.1/) specification. Although one-step authentication is still supported, the API will no longer default to this. If needing to retain this setting, it is necessary to set [flowType](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#flowType) to `implicit`. * * Please refer to the [4.23 Release Notes](https://developers.arcgis.com/javascript/latest/release-notes/#updated-oauth-authentication) for additional information regarding this update. * * @since 4.0 * @see [Sample - Access ArcGIS Online items using OAuth 2.0](https://developers.arcgis.com/javascript/latest/sample-code/identity-oauth-basic/) * @see [Authentication and secure resources](https://developers.arcgis.com/javascript/latest/secure-resources/) * @see [Authentication and OAuth 2](https://developers.arcgis.com/authentication/) * @see [Proxy pages with the API](https://developers.arcgis.com/javascript/latest/proxies/) * @see [ArcGIS portals](https://developers.arcgis.com/javascript/latest/arcgis-organization-portals/) * @see [IdentityManager](https://developers.arcgis.com/javascript/latest/references/core/identity/IdentityManager/) * @see [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth) */ export default class OAuthInfo extends JSONSupport { /** * @example * const [OAuthInfo, esriId] = await $arcgis.import([ * "@arcgis/core/identity/OAuthInfo.js", * "@arcgis/core/identity/IdentityManager.js" * ]); * // Create a new OAuthInfo object. * // The OAuth sign-in page will be shown in a popup window and use the specified callback URL. * const info = new OAuthInfo({ * appId: "<put client id here>", * popup: true, * // If using a callback page other than the default one, * // make sure it supports the authentication type used. * popupCallbackUrl: "<url to callback page>" * }); * * // Add this OAuthInfo object to the IdentityManager. * esriId.registerOAuthInfos([info]); */ constructor(properties?: OAuthInfoProperties); /** The registered application id. */ accessor appId: string | null | undefined; /** * Applications with the same value will share the stored token on the same host. * * @default "/" */ accessor authNamespace: string; /** * The number of minutes that the token is valid. * * @default 20160 // two weeks */ accessor expiration: number; /** * Set this property to specify the type of authentication to use. One-step authentication has been superseded in favor of the recommended two-step approach (ie. [`grant_type=authorization-code`](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/oauth-2/#oauth-20-grant-types)). * * > [!WARNING] * > * > This update coincides with recommendations in the [OAuth 2.1](https://oauth.net/2.1/) recommendation. * * Possible Value | Description * ---------------|------------ * auto | **Recommended.** Automatically defaults to two-step authentication with [PKCE](https://oauth.net/2/pkce/) if accessing resources from ArcGIS Online or ArcGIS Enterprise version 10.9 or higher. One-step authentication is used if accessing an earlier version of ArcGIS Enterprise. * authorization-code | Similar to `auto`, this also uses two-step authentication with [PKCE](https://oauth.net/2/pkce/), but this does not check the server version. **Do not use this type if accessing resources on older server versions without PKCE support.** * implicit | One-step authentication. This is no longer a recommended approach and has been superseded by two-step authentication. Use this type if working with older server versions (ie. prior to 10.9). Please refer to [OAuth 2.0 Security Best Current Practices](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-14#section-2.1.2) for additional information. * * > [!WARNING] * > * > When signing into an application via a [popup](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popup), the referenced [callback page](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popupCallbackUrl) should be compatible for whatever authentication type is used. The default [oauth-callback.html](https://github.com/Esri/jsapi-resources/blob/main/oauth/oauth-callback.html) has been updated to allow for these updates in the two-step approach, although it will still work if using the one-step flow. * * @default "auto" * @since 4.23 * @example * // The `flowType` defaults to `auto`. * // If using a supported server/portal version, two-step authentication is used. * // If not, reverts to one-step. * const infoAuto = new OAuthInfo({ * appId: "<put client id here>" * }); * @example * // One-step workflow - no longer recommended. * // Should only be used if working with older versions of Server/Portal, (ie. < 10.9). * const infoImplicit = new OAuthInfo({ * appId: "<put client id here>", * flowType: "implicit", * popup: true, * // Updated callback page works with both two-step and one-step authentication * popupCallbackUrl: "oauth-callback.html" * }); */ accessor flowType: "auto" | "authorization-code" | "implicit"; /** * Set this property to `true` to force the user to sign in with the id in [userId](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#userId). * If the [userId](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#userId) is not set, it will update after the user signs in. If the token expires, the same user will be required to sign in again. * * @default false * @since 4.18 * @see [userId](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#userId) */ accessor forceUserId: boolean; /** * The locale for the OAuth sign-in page. The default locale * is based on your browser/OS and the organization locale. * You can use this property to change * this. The locale needs to follow the language dash country code * syntax supported by ArcGIS.com. * * @default // Based on your browser/OS and the organization locale. * @see [intl](https://developers.arcgis.com/javascript/latest/references/core/intl/) */ accessor locale: string | null | undefined; /** * The minimum time in minutes before a saved token is due to expire that * should still be considered valid for use. * * @default 30 */ accessor minTimeUntilExpiration: number; /** * Set to `true` to show the OAuth sign-in page in a popup window. Make certain to have a valid callback page referenced in the [popupCallbackUrl](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popupCallbackUrl). A sample callback page, [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth), is provided to help with this. * The referenced [callback page](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popupCallbackUrl) should be compatible for whatever [authentication type](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#flowType) is used. The default [oauth-callback.html](https://github.com/Esri/jsapi-resources/blob/main/oauth/oauth-callback.html) has been updated to allow for these updates in the two-step approach, although it will still work if using the one-step flow. * * @default false * @see [flowType](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#flowType) * @see [popupCallbackUrl](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popupCallbackUrl) * @see [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth) */ accessor popup: boolean; /** * Applicable if working with the popup user-login workflow. * This is a relative page URL that redirects the user back to * the secured application after successful login. * * The referenced callback page should be compatible for whatever [authentication type](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#flowType) is used. The default [oauth-callback.html](https://github.com/Esri/jsapi-resources/blob/main/oauth/oauth-callback.html) has been updated to allow for these updates in the two-step approach, although it will still work if using the one-step flow. * * @default "oauth-callback.html" * @see [popup](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popup) * @see [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth) */ accessor popupCallbackUrl: string; /** * The window features passed to * [window.open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open). * * @default "height=490,width=800,resizable,scrollbars,status" */ accessor popupWindowFeatures: string; /** * The URL to either an ArcGIS Online or an ArcGIS Enterprise portal. * For example, `https://www.arcgis.com`, or `https://www.example.com/arcgis`. * An organization URL can be specified if wanting to display the organization's settings; e.g `https://yourorg.maps.arcgis.com`. * See the [ArcGIS portal documentation](https://developers.arcgis.com/javascript/latest/arcgis-organization-portals/) for more information. * * @default "https://www.arcgis.com" */ accessor portalUrl: string; /** * Set this property to `true` when [popup](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popup) is `false` in order to have the window's location hash value restored after signing in. * * @default false * @since 4.14 * @see [popup](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#popup) */ accessor preserveUrlHash: boolean; /** * The user id used when `forceUserId` is `true`. This is updated after a user * signs in, or it can be preset to a specific id. * * @since 4.18 * @see [forceUserId](https://developers.arcgis.com/javascript/latest/references/core/identity/OAuthInfo/#forceUserId) */ accessor userId: string | null | undefined; /** * Creates a copy of the OAuthInfo object. * * @returns Returns a copy of the OAuthInfo. * @since 4.4 */ clone(): OAuthInfo; }