Auth SDK

The @sdk/auth library facilitates identity handling across various applications by utilizing a set of adapters for different authentication providers. For comprehensive account management features, including user authentication, refer to @sdk/account.

It's important to understand that the SDK Authentication Library focuses on providing an identity, which is an ID representing a logged-in user. This identity is crucial for authentication purposes but does not directly include detailed user data such as names, email addresses, or roles. To work with actual user data, the @sdk/account library utilizes the identity obtained from @sdk/auth to fetch and manage the user's detailed information. This separation of concerns allows @sdk/auth to remain lightweight and focused on authentication, while @sdk/account handles the complexities of user account management.

Installation

To install this package, you need to have access to the private @sdk npm scope.

npm install @sdk/auth

Vanilla JavaScript/TypeScript

The library is designed to be straightforward to use in both JavaScript and TypeScript projects. Below is an example demonstrating how to use the CognitoAuthService for signing in a user.

import { CognitoAuthService } from '@sdk/auth';
 
// Initialize the Cognito authentication service
const auth = new CognitoAuthService();
 
// Attempt to sign in with user credentials
const result = auth.signIn({ email: '', password: '' });

This example illustrates the basic usage pattern, initializing the authentication service and then using it to sign in a user with their email and password.

Supported Authentication Providers

CognitoAuthService: Provides authentication using Amazon Cognito, a managed service that simplifies user authentication and authorization. This adapter is deprecated and will be removed. Use HxAuthService instead which wraps Cognito.
HxAuthService: Provides authentication using the Hx authentication service, a custom authentication provider.

Integration with React

For projects using React, a specific package @sdk/auth-react is provided to integrate authentication seamlessly into your React application. This package provides an AuthProvider component and a corresponding hook useAuth to access the authentication service within your components.

First, install the React-specific package along with its dependencies:

npm install @sdk/auth-react react react-dom

Next, integrate the authentication service with your React application by wrapping your app's root component with the AuthProvider component, passing the authentication service as a prop.

import { AuthProvider } from '@sdk/auth-react';
import { CognitoAuthService } from '@sdk/auth';
 
// Initialize the authentication service
const auth = new CognitoAuthService();
 
function Root() {
  return (
    <AuthProvider authService={auth}>
      <App />
    </AuthProvider>
  );
}
 
function App() {
  // Access the authentication service from the context
  const { authService } = useAuth();
 
  // Define a login handler using the authentication service
  const handleLogin = (email: string, password: string) => {
    authService.signIn({ email, password });
  };
 
  // Render your component...
}

Managing User Identity and Session Tokens

The SDK Authentication Library provides mechanisms to manage user identities and session tokens, essential for building secure and user-friendly applications.

Working with Identity

Determining whether a user is logged in or not is a common requirement. The library offers utility functions such as isAnonymousIdentity to check the current user's identity status. Here’s how you can obtain and evaluate the current identity:

import { Auth } from '@sdk/auth';
 
// Obtain the current identity from the authentication service
const currentIdentity = await myAuth.getCurrentIdentity();
 
// Check if the current identity is anonymous (not logged in)
if (Auth.isAnonymousIdentity(currentIdentity)) {
  console.log('Not logged in!');
  return;
}
 
// Proceed with operations that require a logged-in user...

Session Token

In addition to managing user identity, obtaining the current session token is crucial for authenticated sessions. The session token is typically used for making authenticated requests to your backend or API.

Here’s how to retrieve the current session token using the SDK Authentication Library:

import { SessionToken } from '@sdk/auth';
import { Option } from '@sdk/core';
 
// Retrieve the current session token as an Option type
const tokenOption = await myAuth.getCurrentSessionToken();
 
// Extract the token value, providing a fallback if it's unavailable
const token: SessionToken | undefined = Option.unwrapOr(tokenOption, undefined);
 
if (token) {
  // Use the session token for authenticated requests
} else {
  // Handle the absence of a session token (e.g., user not logged in)
}

The use of the Option type from @sdk/core ensures that your code handles the possible absence of a session token in a type-safe manner, avoiding common pitfalls like null references.

Schema Account