npm package: @portalgaming/id
Description: Identity module for Portal Platform
Author: Portal
Latest version: 0.0.1-alpha-24

# Portal.js Identity

The Portal Identity library provides an SDK that enables easy integration with the portal platform oauth provider, user
management, account abstraction and blockchain transaction utilities for the Portal Wallet.

### Installation

```bash
npm i @portalgaming/id
```

### Basic usage

To use the ID you'll need to configure it. The most basic configuration, with the required fields, is as follows:

```javascript
import { IdentityModuleConfiguration, Identity } from '@portalgaming/id';

const config: IdentityModuleConfiguration = {
  scope: 'openid profile', // The scopes that the client will request from the user
  redirectUri: REDIRECT_URI, // The URI to redirect after the user has logged in and where the client will need to call the `loginCallback`
  clientId: CLIENT_ID, // The client id of the OAuth client that is going to be used
};

const IdentityClient = new Identity(config);
```

### Advanced configuration

There's a subset of configurations that can be used to customize the behavior of the Identity SDK. The full list of
configurations can be found below:

```javascript
import {
  IdentityModuleConfiguration,
  Identity
} from '@portalgaming/id';
const config: IdentityModuleConfiguration => {
  scope: "openid profile", // The scopes that the client will request from the user
  redirectUri: REDIRECT_URI, // The URI to redirect after the user has logged in and where the client will need to call the `loginCallback`
  clientId: CLIENT_ID, // The client id of the OAuth client that is going to be used

  // Optional configurations
  loginMode: 'popup' | 'redirect', // The flow that the client will use to login the user. The default is 'popup'
  logoutMode: 'silent' | 'redirect', // The mode that the client will use to logout the user. The default is 'silent'
  logoutRedirectUri: LOGOUT_REDIRECT_URI, // The URI to redirect after the user has logged out. This is required when the `logoutMode` is set to 'redirect'.
  authProviderOrigin: AUTHENTICATION_ORIGIN, // The authentication domain with scheme. Defaults to a value for using Portal Platform.
  authProviderAuthorizeEndpoint: AUTHORIZE_ENDPOINT, // The endpoint for obtaining an authorization code. Defaults to a value for using Portal Platform.
  authProviderDeviceCodeEndpoint: DEVICE_CODE_ENDPONT, // The endpoint for obtaining a device code. Defaults to a value for using Portal Platform.
  authProviderUserEndpoint: USER_ENDPOINT, // The endpoint for obtaining information about the current user.  Defaults to a value for using Portal Platform.
  authProviderTokenEndpoint: TOKEN_ENDPOINT, // The endpoint that the client will use to exchange the code for the token. Defaults to a value for using Portal Platform.
  authProviderLogoutEndpoint: LOGOUT_ENDPOINT, // The endpoint for logging out the current user. Defaults to a value for using Portal Platform.
  apiOrigin: API_ORIGIN, // The api domain with scheme. This is used for transactions. Defaults to a value for using Portal Platform.
  apiExecuteTransactionEndpoint: TRANSACTION_ENDPOINT, // The endpoint for executing transactions using a session key. Defaults to a value for using Portal Platform.
  apiCreateTransactionIntentEndpoint: TRANSACTION_INTENT_ENDPOINT, // The endpoint for creating transaction intents. Defaults to a value for using Portal Platform.
  apiConfirmTransactionEndpoint: TRANSACTION_CONFIRM_ENDPOINT, // The endpoint for confirming transaction intents with an externally create signature. Defaults to a value for using Portal Platform.
  signerOrigin: SIGNER_ORIGIN, // The signer domain with scheme. Defaults to a value for using Portal Platform.
  signerSessionKeyEndpoint: SESSION_KEY_ENDPOINT, // The endpoint for creating session keys. Defaults to a value for using Portal Platform.
  signerSignMessageEndpoint: SIGN_ENDPOINT, // The endpoint for signing messages. Defaults to a value for using Portal Platform.
  disableGenericPopupOverlay: true | false, // Disables the full screen overlay created when using the popup signin and signer flows. Defaults to false.
  disableBlockedPopupOverlay: true | false, // Disables the full screen overlay created when popups are blocked when using the popup signin and signer flows. Defaults to false.
};

const IdentityClient = new Identity(config)
```

### OAuth Flow

The SDK provides a set of methods that can be used to interact with the OAuth provider. The most common methods are:

```javascript
// This method will redirect the user to the OAuth provider login page
await identityClient.authenticate();

// This method will handle the callback from the OAuth provider and return the user information
const user = await identityClient.loginCallback();

// This method will logout the user from the OAuth provider
await identityClient.logout();

// This method will return the user information
const user = await identityClient.getUserInfo();

// This method will return the access token
const token = await identityClient.getAccessToken();

// This method will return the id token
const idToken = await identityClient.getIdToken();
```