tessl/npm-aws-sdk--credential-providers

A collection of credential providers for AWS SDK, enabling authentication across different AWS environments and services

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Cognito Identity Credentials

Name: tessl/npm-aws-sdk--credential-providers
Author: tessl

Cognito Identity credential providers retrieve temporary AWS credentials using Amazon Cognito Identity pools and identities, supporting both authenticated and unauthenticated access for mobile and web applications.

Capabilities

Cognito Identity Provider

Retrieves credentials for a specific Cognito Identity using the GetCredentialsForIdentity API.

/**
 * Creates a credential provider that retrieves temporary AWS credentials using Amazon Cognito's
 * GetCredentialsForIdentity operation
 * @param options - Configuration parameters for the Cognito Identity provider
 * @returns Cognito Identity credential provider function
 */
function fromCognitoIdentity(options: FromCognitoIdentityParameters): CognitoIdentityCredentialProvider;

interface FromCognitoIdentityParameters {
  /** The unique identifier for the identity against which credentials will be issued */
  identityId: string;
  /** Optional ARN of role to assume when multiple roles were received from identity provider */
  customRoleArn?: string;
  /** Optional set of name-value pairs mapping provider names to provider tokens */
  logins?: Record<string, string>;
  /** Optional custom Cognito Identity client configuration */
  clientConfig?: CognitoIdentityClientConfig;
}

Usage Examples:

import { S3Client } from "@aws-sdk/client-s3";
import { fromCognitoIdentity } from "@aws-sdk/credential-providers";

// Basic Cognito Identity credentials
const client = new S3Client({
  region: "us-east-1",
  credentials: fromCognitoIdentity({
    identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f"
  })
});

// With external identity provider logins
const authenticatedClient = new S3Client({
  region: "us-east-1",
  credentials: fromCognitoIdentity({
    identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
    logins: {
      "graph.facebook.com": "FBTOKEN",
      "accounts.google.com": "GOOGLETOKEN",
      "www.amazon.com": "AMAZONTOKEN"
    }
  })
});

// With custom role and client configuration
const customClient = new S3Client({
  region: "us-east-1",
  credentials: fromCognitoIdentity({
    identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
    customRoleArn: "arn:aws:iam::123456789012:role/MYAPP-CognitoIdentity",
    clientConfig: {
      region: "us-east-1",
      maxAttempts: 3
    }
  })
});

Cognito Identity Pool Provider

Retrieves or generates a unique identifier using GetId API, then gets credentials using GetCredentialsForIdentity API.

/**
 * Creates a credential provider that retrieves or generates a unique identifier using Amazon Cognito's GetId
 * operation, then generates temporary AWS credentials using GetCredentialsForIdentity operation
 * @param options - Configuration parameters for the Cognito Identity Pool provider
 * @returns Cognito Identity credential provider function
 */
function fromCognitoIdentityPool(options: FromCognitoIdentityPoolParameters): CognitoIdentityCredentialProvider;

interface FromCognitoIdentityPoolParameters {
  /** The unique identifier for the identity pool from which an identity should be retrieved or generated */
  identityPoolId: string;
  /** Optional standard AWS account ID (9+ digits) */
  accountId?: string;
  /** Optional cache in which to store resolved Cognito IdentityIds */
  cache?: any;
  /** Optional unique identifier for the user used to cache Cognito IdentityIds on a per-user basis */
  userIdentifier?: string;
  /** Optional ARN of role to assume when multiple roles were received from identity provider */
  customRoleArn?: string;
  /** Optional set of name-value pairs mapping provider names to provider tokens */
  logins?: Record<string, string>;
  /** Optional custom Cognito Identity client configuration */
  clientConfig?: CognitoIdentityClientConfig;
}

Usage Examples:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers";

// Basic Identity Pool credentials (unauthenticated)
const client = new DynamoDBClient({
  region: "us-east-1",
  credentials: fromCognitoIdentityPool({
    identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030"
  })
});

// With user identification and caching
const userClient = new DynamoDBClient({
  region: "us-east-1",
  credentials: fromCognitoIdentityPool({
    identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
    accountId: "123456789012",
    userIdentifier: "user_123",
    cache: new Map() // Simple in-memory cache
  })
});

// With external provider authentication
const socialClient = new DynamoDBClient({
  region: "us-east-1",
  credentials: fromCognitoIdentityPool({
    identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
    logins: {
      "graph.facebook.com": "EAAFacebookToken",
      "accounts.google.com": "GoogleOAuthToken"
    },
    customRoleArn: "arn:aws:iam::123456789012:role/AuthenticatedRole"
  })
});

Supported External Identity Providers

The logins parameter supports tokens from various identity providers:

Facebook: "graph.facebook.com"
Google: "accounts.google.com"
Amazon: "www.amazon.com"
Twitter: "api.twitter.com"
Digits: "www.digits.com"
OpenID Connect providers: "oidc.example.com"
SAML providers: "saml.example.com"

Identity Pool vs Identity ID

Use fromCognitoIdentityPool when:

You have an Identity Pool ID and want automatic identity management
You need caching of identity IDs for performance
You're building a new application with Cognito authentication

Use fromCognitoIdentity when:

You already have a specific Identity ID
You're integrating with existing Cognito Identity workflows
You need direct control over the identity used

Caching Behavior

fromCognitoIdentityPool:

Results from GetId are cached internally for performance
Results from GetCredentialsForIdentity are NOT cached
Custom cache can be provided via cache parameter

fromCognitoIdentity:

Results are not cached internally
Each call makes a fresh request to GetCredentialsForIdentity

Error Handling

Common errors and handling:

import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers";

try {
  const credentials = await fromCognitoIdentityPool({
    identityPoolId: "invalid-pool-id"
  })();
} catch (error) {
  if (error.name === "NotAuthorizedException") {
    console.error("Identity pool not found or access denied");
  } else if (error.name === "InvalidParameterException") {
    console.error("Invalid identity pool ID format");
  } else if (error.name === "ResourceNotFoundException") {
    console.error("Identity pool does not exist");
  } else {
    console.error("Failed to get Cognito credentials:", error.message);
  }
}

Custom Client Configuration

import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers";

const credentials = fromCognitoIdentityPool({
  identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
  clientConfig: {
    region: "us-east-1",
    maxAttempts: 5,
    requestTimeout: 10000,
    credentials: otherCredentialsForCognitoClient
  }
});