@trimble-oss/trimble-id-react 0.0.1-rc.1

package/README.md

@@ -0,0 +1,186 @@
+# @trimble-oss/trimble-id-react
+
+Trimble Identity SDK for React app.
+
+🚀 [Getting Started](#getting-started) - 📚 [Usage Reference](#usage-reference) - 💬 [Support](#support)
+
+## <a name="getting-started">Getting Started</a>
+
+### Installation
+
+Using [npm](https://npmjs.org) in your project directory run the following command:
+
+```sh
+npm install @trimble-oss/trimble-id-react
+```
+
+### Configure Trimble Identity
+
+Create a new application in the [Trimble Developer Console](https://developer.console.trimble.com) portal and configure the following settings:
+
+To register your service application in Trimble Developer Console:
+
+1. On the left pane select Identity Management > Applications.
+
+2. On the Applications home page, in the top right corner select + NEW APPLICATION. The Create Application page displays.
+
+3. Select Continue to enter the applications details.
+
+    | Field       | Description |
+    | ----------- | ----------- |
+    | Name        | Name of your application                    |
+    | Display Name| Provide a display name of the application.  |
+    | Description | Provide a description for the application.  |
+
+4. Configure OAuth application grant types as `Authorization Code Grant` and `Use Refresh tokens` in order to use this SDK.
+
+5. Select "Create Application" to save changes.
+
+Take note of the Client ID and URLs under the "Basic Information" section. You'll need these values to configure the SDK.
+
+For more information, see [Authentication documentation](https://developer.trimble.com/docs/authentication).
+
+## <a name="usage-reference">Usage Reference</a>
+
+### Configure the SDK
+
+SDK provides a React component `TID Provider` that will handle the
+process related to the authentication for you. Configure the SDK by wrapping your application in `TIDProvider`:
+
+```tsx
+<TIDProvider tidClient={new TIDClient(config)} onRedirectCallback={handleRedirect}>
+    <Component/>
+</TIDProvider> 
+```
+
+Here TIDProvider can take two parameters :  
+* **tidClient**  : TID client instance. You can send an instance of the TID Client if you want to handle the initialization yourself
+* **onRedirectCallback** -  When the redirect callback occur this function will be call once the user is login using the TIDClient. This could allow you to redirect the user into another page after the login happen.
+
+
+After wrapping your app with the TIDProvider, you have to configure the TID credentials registered in TrimbleCloud console. There are two ways of doing this:
+
+**1.** Using the `TIDClient`
+```tsx
+<TIDProvider tidClient={new TIDClient({
+    config: {
+        configurationEndpoint: "<OAUTH_WELL_KNOWN_URL>",
+        clientId: "CLIENT_ID",
+        redirectUrl: "http://localhost:3000/callback",
+        logoutRedirectUrl: "http://localhost:3000/logout-callback",
+        scopes: ['test']
+    },
+    persistentOptions: {
+      persistentStore:   ('localStorage' as PersistentStore),
+  }
+  })} onRedirectCallback={handleRedirect}>
+    <Component/>
+</TIDProvider>
+```
+**2.** You can send the properties directly
+
+```tsx
+<TIDProvider
+    configurationEndpoint={"<OAUTH_WELL_KNOWN_URL>"}
+    clientId={"CLIENT_ID"}
+    redirectUrl={"http://localhost:3000/callback"}
+    logoutRedirectUrl={"http://localhost:3000/logout-callback"}
+    scopes={['test']}
+    onRedirectCallback={handleRedirect}>
+        <Component/>
+</TIDProvider>
+```
+
+Below are the parameters of TIDClient.
+### 1. TID Client configurations:
+
+* **ConfigurationEndpoint** : The URL for the Trimble Identity OpenID well known configuration endpoint <br /> 
+Production: https://id.trimble.com/.well-known/openid-configuration  <br /> 
+* **clientId** : Client id of the application created in Trimble Developer Console
+* **redirectUrl** : The URL to which Trimble Identity should redirect after successfully authenticating a user
+* **logoutRedirectUrl** : The URL to which Trimble Identity should redirect after successfully logout a user
+* **scopes** :  The type of credentials you want (openID, or application_name)
+
+### 2. PersistentOptions configuration
+Type of persistence you want the user and token to be store
+   * **localStorage** - This persistent doesn't have expiration date
+   * **sessionStorage** - This one is cleared when the page session ends
+
+Use the `useAuth` hook in your components to access authentication state (`isLoading`, `isAuthenticated` and `user`) and authentication methods (`loginWithRedirect` and `logout`):
+
+### loginWithRedirect
+
+Redirect the user to TID using the browser
+
+```tsx
+const {loginWithRedirect}= useAuth()
+await loginWithRedirect()
+
+```
+
+### logout
+
+```tsx
+const {logout}= useAuth()
+await logout()
+```
+
+### isAuthenticated
+
+True if the user is authenticated.
+
+```tsx
+const {isAuthenticated}= useAuth()
+```
+
+### isLoading 
+
+This property will indicate the developer that the TID Provider is still loading information from the cache By default, this state will be true, this will allow the developers to handle async functionality Note: This property will only be true the first time that the app executes.
+
+```tsx
+const {isLoading}= useAuth()
+```
+
+### getAccessTokenSilently
+
+Gets the access token from cache. SDK handles token refresh when token expires.
+
+```tsx
+const {getAccessTokenSilently}= useAuth()
+var access_token = await useAuth().getAccessTokenSilently()
+```
+
+### user
+
+Information of the user in session
+
+```tsx
+const {user}= useAuth()
+var name = user?.name
+```
+
+
+### AuthenticationGuard 
+It renders a component if the user is authenticated, otherwise redirects the user to the login page. It can be used to protect private components. If the user is not authenticated, they will be redirected to the login page.
+
+```tsx
+<AuthenticationGuard renderComponent={() => <MyPrivateComponent/>}/>
+```
+
+> **_NOTE:_** Refer samples for better understanding.
+
+## Sample Code
+
+See here for [Sample Code](https://github.com/trimble-oss/trimble-id-sdk-docs-for-react/blob/main/samples) for reference.
+
+## Release notes
+
+See here for [releases](https://github.com/trimble-oss/trimble-id-sdk-docs-for-react/blob/main/release-notes/CHANGELOG.md)
+
+## Raise an issue
+
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/trimble-oss/tcp-sdk-docs-for-net/issues).
+
+## <a name="support">Support</a>
+
+Send email to [cloudplatform_support@trimble.com](mailto:cloudplatform_support@trimble.com)

package/dist/AuthenticationGuard/AuthenticationGuard.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { ReactElement } from 'react';
+interface IAuthenticationGuard {
+    renderComponent: ReactElement;
+    loader?: ReactElement;
+}
+/**
+ * Renders a component if the user is authenticated, otherwise redirects the user to the login page.
+ * @param renderComponent The component to render if the user is authenticated
+ * @param loader The component to render while TIDProvider is loading
+ */
+export declare const AuthenticationGuard: ({ renderComponent, loader }: IAuthenticationGuard) => React.JSX.Element;
+export default AuthenticationGuard;

package/dist/TIDClient/TIDClient.d.ts

@@ -0,0 +1,207 @@
+import { BearerTokenHttpClientProvider } from '@trimble-oss/trimble-id';
+import { PersistentStore } from './storage/cache-storage/CacheManager';
+import { AuthState, TIDUser } from './interfaces';
+interface TIDClientConfig {
+    /**
+     * The URL for the Trimble Identity OpenID well known configuration endpoint
+     * Staging: https://stage.id.trimblecloud.com/.well-known/openid-configuration
+     * Production: https://id.trimble.com/.well-known/openid-configuration
+     * @type {string}
+     */
+    configurationEndpoint: string;
+    /**
+     * Client id of the application created in trimble developer console
+     * @type {string}
+     */
+    clientId: string;
+    /**
+     * The URL to which Trimble Identity should redirect after successfully authenticating a user
+     * @type {string}
+     */
+    redirectUrl: string;
+    /**
+     * The URL to which Trimble Identity should redirect after successfully logout a user
+     * @type {string}
+     */
+    logoutRedirectUrl: string;
+    /**
+     * The type of credentials you want (openID, or application_name)
+     * @type {string[]}
+     */
+    scopes: string[];
+}
+interface LoginWithRedirectOptions {
+    /**
+     * Function called when the user redirection is occurring
+     * If you send this function you will need to handle the redirection
+     * @param {string} url - Redirect url to TID with the necessary information to log in the user
+     */
+    onRedirect?: (url: string) => void;
+}
+interface PersistentOptions {
+    /**
+     * Type of persistent store you want the user and token to be stored
+     *
+     * in-memory - This one will only persist will the user stays in the page
+     *
+     * localStorage - This persistent doesn't have expiration date
+     *
+     * sessionStorage - This one is cleared when the page session ends
+     * @type {PersistentStore}
+     */
+    persistentStore: PersistentStore;
+}
+interface LogoutOptions {
+    /**
+     * Function called when the user redirection is occurring
+     * If you send this function you will need to handle the redirection
+     * @param {string} url - Redirect url to TID with the necessary information to log out the user
+     */
+    onRedirect?: (url: string) => void;
+    /**
+     * If you want to disable the auto redirect to TID after the logout is successful you can set this to true
+     * If you set this to true you will need to handle the redirection and the provider will clear the user information from the context
+     *
+     * **IMPORTANT**: If you set this to true the user information will be cleared from the context and isAuthenticated will be false
+     * if you are using the AuthenticationGuard component it will redirect the user to the login page automatically
+     * @default false
+     * @type {boolean}
+     * @example
+     * logout({disabledAutoRedirect: true})
+     */
+    disabledAutoRedirect?: boolean;
+}
+export interface TIDClientOptions {
+    /**
+     * TID client configuration
+     * @type {TIDClientConfig}
+     */
+    config: TIDClientConfig;
+    /**
+     * Persistent options configuration
+     * @type {PersistentOptions}
+     */
+    persistentOptions?: PersistentOptions;
+}
+export declare class TIDClient {
+    /**
+     * Token provider SDK. This object handles all necessary communication with TID
+     * @type {AuthorizationCodeGrantTokenProvider}
+     */
+    private tokenProvider;
+    /**
+     * This object manage all caching, and all configurations necessary
+     * @type {CacheManager}
+     */
+    private readonly cacheManager;
+    /**
+     * This object manage all cookies administration, and all configurations necessary
+     * @type {CookiesManager}
+     */
+    private readonly cookiesManager;
+    /**
+     * Client id of the application created in trimble developer console
+     * @type {string}
+     */
+    private readonly clientId;
+    /**
+     * Callback url to redirect the user after the authentication is successful
+     * @type {string}
+     */
+    private readonly redirectUrl;
+    /**
+      * AnalyticsHttpClient for sending events
+      * @type {AnalyticsHttpClient}
+      */
+    private readonly analyticshttpclient;
+    /**
+     * Create a TID client to handle manage all user authentication functions and information
+     * @param {CacheManagerOptions} props - TID client configuration
+     */
+    constructor(props: TIDClientOptions);
+    /**
+     * Redirect the user to TID using the browser
+     * @param {LoginWithRedirectOptions} options - Custom configuration for the redirection
+     * @return {Promise<void>} Empty promise
+     * @example No configuration
+     * loginWithRedirect()
+     * // Automatically redirects the user to TID with all necessary parameters
+     * @example Custom redirect
+     * loginWithRedirect({onRedirect: (url) => router.navigate(url)})
+     * // Redirect calls onRedirect with the log-out url for TID
+     * // So it can be handled by the developer
+     */
+    loginWithRedirect(options?: LoginWithRedirectOptions): Promise<void>;
+    /**
+     * Authenticated the user using the url callback params
+     * @param {string} url - Custom configuration for the redirection
+     * @return {Promise<AuthState>} Object contain the state returned from TID
+     * @throws {CodeVerifierNotFoundException} Will throw an exception if the session doesn't contain the code verifier
+     * @example No configuration
+     * handleCallback()
+     * // Will automatically take the url from the browser and try to log in the user
+     * @example Custom url
+     * handleCallback('https://example.com?code=code....')
+     * // Will try to log in the user with the url assign by the developer
+     */
+    handleCallback(url?: string): Promise<AuthState>;
+    /**
+     * Function to generate and store the access token
+     * @param {string} identityProvider - Type of identity provider used
+     * @return {Promise<void>} Empty promise
+     */
+    private generateToken;
+    private reloadCodeVerifier;
+    /**
+     * Return the user stored in cache
+     * @return {Promise<TIDUser | undefined>} User in cache
+     */
+    getUser(): Promise<TIDUser | undefined>;
+    /**
+     * Gets the access token from cache. If the token already expired,
+     * will try to refresh it using the refresh token
+     * @return {Promise<string>} Access token
+     * @throws {TokenNotFoundException} Will throw an exception if the access token is not in cache
+     * @throws {TokenExpiredException} Will throw an exception if the user token expired
+     */
+    getAccessTokenSilently(): Promise<string>;
+    /**
+     * Redirect the user to TID using the browser
+     * @param {LogoutOptions} options - Custom configuration for teh redirection
+     * @return {Promise<void>} Empty promise
+     * @example No configuration
+     * logout()
+     * // Automatically redirects the user to TID to log out
+     * @example Custom redirect
+     * logout({onRedirect: (url) => router.navigate(url)})
+     * // Redirect calls onRedirect with the log-out url for TID
+     * // So it can be handled by the developer
+     */
+    logout(options?: LogoutOptions): Promise<void>;
+    /**
+     * Check if the user still has a valid session
+     * @return {Promise<boolean>} True or false depending on if the user is session is valid or not
+     */
+    checkSession(): Promise<boolean>;
+    /**
+     * Check if the user has a session valid after a refresh
+     * @return {Promise<void>} Empty promise
+     */
+    loadUserSession(): Promise<void>;
+    /**
+     * Load the user session from cache into the SDK
+     * @return {Promise<void>} Empty promise
+     */
+    private loadCacheSessionIntoSDK;
+    /**
+     * Get a http bearer token client to use it for another SDK (Ex: Processing framework)
+     * @return {any} - BearerTokenHttpClientProvider
+     */
+    getBearerTokenHttpClient(apiURL: string): typeof BearerTokenHttpClientProvider;
+    /**
+     * Get the redirect url to TID
+     * @return {string} - Callback redirect url
+     */
+    getRedirectUrl(): string;
+}
+export {};

package/dist/TIDClient/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default time skew time to check if the token has expired
+ * @type {number}
+ */
+export declare const CLOCK_SKEW_TIME: number;
+/**
+ * List of parameters required in the redirect callback that you get from TID
+ * @type {Array<string>}
+ */
+export declare const LIST_PARAMS_REQUIRED: Array<string>;

package/dist/TIDClient/exceptions.d.ts

@@ -0,0 +1,8 @@
+/** Class representing a token expiration exception */
+export declare class TokenExpiredException extends Error {
+}
+/** Class representing a token expiration exception */
+export declare class TokenNotFoundException extends Error {
+}
+export declare class CodeVerifierNotFoundException extends Error {
+}

package/dist/TIDClient/index.d.ts

@@ -0,0 +1,5 @@
+import { PersistentStore as PS } from './storage/cache-storage/CacheManager';
+export * from './interfaces';
+export * from './TIDClient';
+export * from './utils';
+export type PersistentStore = PS;

package/dist/TIDClient/interfaces.d.ts

@@ -0,0 +1,206 @@
+export interface CacheStorage {
+    getToken: () => Promise<TIDAuthToken | undefined>;
+    storeToken: (authToken: TIDAuthToken) => Promise<void>;
+    getUser: () => Promise<TIDUser | undefined>;
+    storeUser: (user: TIDUser) => Promise<void>;
+    clear: () => Promise<void>;
+}
+export interface TIDAuthToken {
+    /** The id_token returned from the OIDC provider */
+    id_token: string;
+    /** The session state value returned from the OIDC provider (opaque) */
+    session_state?: string;
+    /** The identity provider value returned the provider used for the authentication (okta, email, google, etc..) */
+    identity_provider?: string;
+    /** The access token returned from the OIDC provider. */
+    access_token: string;
+    /** Refresh token returned from the OIDC provider (if requested) */
+    refresh_token?: string;
+    /** The token_type returned from the OIDC provider */
+    token_type: string;
+    /** The scope returned from the OIDC provider */
+    scope: string;
+    /** The expires at returned from the OIDC provider */
+    expires_at: number;
+    /** The custom state transferred in the last signin */
+    state: any;
+}
+export interface TIDUser {
+    /** End-User's full name */
+    name?: string;
+    /** Given name(s) or first name(s) of the End-User */
+    given_name?: string;
+    /** Surname(s) or last name(s) of the End-User */
+    family_name?: string;
+    /** Middle name(s) of the End-User */
+    middle_name?: string;
+    /** Casual name of the End-User that may or may not be the same as the given_name. */
+    nickname?: string;
+    /** Shorthand name that the End-User wishes to be referred to at the RP, such as janedoe or j.doe. */
+    preferred_username?: string;
+    /** URL of the End-User's profile page */
+    profile?: string;
+    /** URL of the End-User's profile picture */
+    picture?: string;
+    /** URL of the End-User's Web page or blog */
+    website?: string;
+    /** End-User's preferred e-mail address */
+    email?: string;
+    /** True if the End-User's e-mail address has been verified; otherwise false. */
+    email_verified?: boolean;
+    /** End-User's gender. Values defined by this specification are female and male. */
+    gender?: string;
+    /** End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format */
+    birthdate?: string;
+    /** String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone. */
+    zoneinfo?: string;
+    /** End-User's locale, represented as a BCP47 [RFC5646] language tag. */
+    locale?: string;
+    /** End-User's preferred telephone number. */
+    phone_number?: string;
+    /** True if the End-User's phone number has been verified; otherwise false. */
+    phone_number_verified?: boolean;
+    /** object    End-User's preferred address in JSON [RFC4627] */
+    address?: OidcAddress;
+    /** Time the End-User's information was last updated. */
+    updated_at?: number;
+}
+interface OidcAddress {
+    /** Full mailing address, formatted for display or use on a mailing label */
+    formatted?: string;
+    /** Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information */
+    street_address?: string;
+    /** City or locality component */
+    locality?: string;
+    /** State, province, prefecture, or region component */
+    region?: string;
+    /** Zip code or postal code component */
+    postal_code?: string;
+    /** Country name component */
+    country?: string;
+}
+export interface TIDJWTUser {
+    /**
+     * The issuer of a token
+     * Prod: https://id.trimble.com
+     * Stage: https://state.id.trimblecloud.com
+     * @type {string}
+     */
+    iss: string;
+    /**
+     * Time on or after which the JWT MUST NOT be accepted for processing
+     * integer, (Seconds since midnight Jan 1, 1970)
+     * @type {number}
+     */
+    exp: number;
+    /**
+     * Not Before Time. Used to determine the age of a JWT
+     * integer, (Seconds since midnight Jan 1, 1970)
+     * @type {number}
+     */
+    nbf: number;
+    /**
+     * Issued At Time. The time the token was issued
+     * integer, (Seconds sing midnight Jan 1, 1970)
+     * @type {number}
+     */
+    iat: number;
+    /**
+     * A unique identifier for the token
+     * @type {string}
+     */
+    jti: string;
+    /**
+     * The version of this Trimble Identity Token
+     * @type {number}
+     */
+    jwt_ver: number;
+    /**
+     * The subject of the JWT
+     * user or application UUID
+     * @type {string}
+     */
+    sub: string;
+    /**
+     * Audience an array of relying parties (client ID tokens) user or application UUID
+     * For access tokens: an array of unique IDs for applications/APIs intended to consume this token
+     * For ID token tokens: this is a single string ID in the application that made the authentication request
+     * @type {string}
+     */
+    aud: string;
+    /**
+     * Logged user type (user or application)
+     * @type {string}
+     */
+    identity_type: string;
+    /**
+     * The time when the authentication occurred
+     * integer, (Seconds since midnight Jan 1, 1970)
+     * @type {number}
+     */
+    auth_time: number;
+    /**
+     * Authentication Methods References
+     * An array of strings giving information about how the user is authenticated
+     *
+     * Examples: password
+     * mfa
+     * sms_mfa
+     * software_token_mfa
+     * federated
+     * trimble_okta
+     * client_credentials
+     * @type {Array<string>}
+     */
+    amr: Array<string>;
+    /**
+     * Authorizing Party. Relying party’s client ID token
+     * @type {string}
+     */
+    azp: string;
+    /**
+     * Hash of the accompanying access token
+     * @type {string}
+     */
+    at_hash: string;
+    /**
+     * The federated system the user is signed in to
+     * e.g., trimble_okta
+     * @type {string}
+     */
+    federation_origin: string;
+    /**
+     * Firstname or full name of this user
+     * @type {string}
+     */
+    given_name: string;
+    /**
+     * Family name or surname of the user
+     * @type {string}
+     */
+    family_name: string;
+    /**
+     * Email address of the user
+     * @type {string}
+     */
+    email: string;
+    /**
+     * Whether the user’s email is verified or not
+     * @type {string}
+     */
+    email_verified: true;
+    /**
+     * URL of user’s profile picture
+     * @type {string}
+     */
+    picture: string;
+    /**
+     * Geographic region that user data is stored in (us/eu)
+     * @type {string}
+     */
+    data_region: string;
+}
+export interface AuthState {
+    authState: any;
+}
+export {};

package/dist/TIDClient/storage/cache-storage/CacheKey.d.ts

@@ -0,0 +1,46 @@
+interface CacheKeyOptions {
+    /**
+     * Client id of the application created in trimble developer console
+     * @type {string}
+     */
+    client_id: string;
+}
+/** Class representing the caching keys for storing and retrieving user and token from auth */
+export declare class CacheKey {
+    /**
+     * Client id of the application created in trimble developer console
+     * @type {string}
+     */
+    private readonly clientId;
+    /**
+     * Prefix value of the key, by default the prefix is based on the constant PREFIX_KEY
+     * @type {string}
+     */
+    private readonly prefix;
+    /**
+     * Suffix value use it to generate the key to store and retrieve the token, by default the prefix is based on the constant AUTH_KEY
+     * @type {string}
+     */
+    private readonly authSuffix;
+    /**
+     * Suffix value use it to generate the key to store and retrieve the user, by default the prefix is based on the constant USER_KEY
+     * @type {string}
+     */
+    private readonly userSuffix;
+    /**
+     * Initialized the cache key
+     * @param {CacheKeyOptions} cacheKeyOptions - Cache key options to edit the default values
+     */
+    constructor(cacheKeyOptions: CacheKeyOptions);
+    /**
+     * Get key to store/retrieve user
+     * @return {string} Key for the user
+     */
+    getUserKey(): string;
+    /**
+     * Get key to store/retrieve token
+     * @return {string} Key for the token
+     */
+    getAuthKey(): string;
+}
+export {};