Skip to main content

Installation & Setup

Installation​

npm install react-native-credentials-manager

# or if you prefer yarn
yarn add react-native-credentials-manager

# or with pnpm
pnpm add react-native-credentials-manager

Platform Requirements​

Android​

  • Minimum Version: Android 4.4 (API 19) or higher
  • AndroidX Support: Required for all versions
  • Feature Requirements:
    • Basic Credentials & Federated Sign-in: Android 4.4+ (API 19+)
    • Full Passkey Support: Android 9+ (API 28+)

iOS​

  • iOS 16.0+
  • Xcode 14.0+
  • React Native 0.71.0+

Android Setup​

To implement the Credential Manager API in your Android application, follow these steps:

To enable passkey support, you need to associate your Android app with your website by creating and hosting a Digital Asset Links JSON file.

Create a file named assetlinks.json with the following content:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "your.package.name",
      "sha256_cert_fingerprints": [
        "YOUR_APP_SIGNING_CERTIFICATE_SHA256_FINGERPRINT"
      ]
    }
  }
]

Host this file at:

https://your-domain.com/.well-known/assetlinks.json

2. Get Your App's SHA-256 Certificate Fingerprint​

To get your app's SHA-256 certificate fingerprint, you can use the following command:

For Debug Build:​

cd android && ./gradlew signingReport

Look for the SHA-256 fingerprint in the "debugAndroidTest" variant.

For Release Build:​

If you're using a keystore file for signing your release builds:

keytool -list -v -keystore your-keystore.keystore -alias your-key-alias

Replace your-keystore.keystore and your-key-alias with your actual keystore file path and alias.

3. Manifest Configuration​

No additional manifest configuration is required for basic functionality. The library automatically sets up the necessary AndroidX Credential Manager dependencies.

4. ProGuard Configuration​

If you're using ProGuard in your Android application, add these rules to your android/app/proguard-rules.pro:

-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
  *;
}

iOS Setup​

To implement Authentication Services in your iOS application, follow these steps:

1. Add Associated Domains Capability​

  1. In Xcode, select your project
  2. Go to the "Signing & Capabilities" tab
  3. Click "+" and add "Associated Domains"
  4. Add your domain with the webcredentials service: 
    webcredentials:yourdomain.com

2. Create Apple App Site Association (AASA) File​

Create a file named apple-app-site-association (no file extension) with the following content:

{
  "webcredentials": {
    "apps": ["TEAMID.com.yourcompany.yourapp"]
  }
}

Replace TEAMID with your Apple Developer Team ID and com.yourcompany.yourapp with your app's bundle identifier.

Host this file at:

https://yourdomain.com/.well-known/apple-app-site-association

3. Configure Sign In with Apple (Optional)​

If you plan to use Apple Sign In:

  1. In Xcode, add the "Sign In with Apple" capability
  2. In your Apple Developer account:
    • Go to "Certificates, Identifiers & Profiles"
    • Select your app identifier
    • Enable "Sign In with Apple"
    • Configure the domains you want to use with Sign In with Apple

4. Info.plist Entries​

No additional Info.plist entries are required as the library automatically configures the necessary entries for Authentication Services.

Google Sign-In Setup (For Android)​

If you plan to use Google Sign-In on Android, follow these steps:

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Click on "APIs & Services"
  4. Navigate to "Credentials" in the left sidebar
  5. Click "Create Credentials" and select "OAuth client ID"
  6. Choose "Android" as the application type
  7. Enter your Android package name (e.g., com.example.app)
  8. Add your application's SHA-1 signing certificate fingerprint: 
    cd android && ./gradlew signingReport
    Run this command in your project directory to get your SHA-1 key
  9. Click "Create" to generate your Android OAuth client ID
  10. Take note of this Android OAuth client ID as you'll need it for your React Native app
  11. Ensure your configuration in the Google Cloud Console matches your app's package name and signing certificate

Important Requirements​

  • The MIME type must be application/json
  • If you have a robots.txt, ensure it allows access to /.well-known/assetlinks.json: 
    User-agent: *
    Allow: /.well-known/
  • The domain must be fully-qualified
  • Don't include trailing slashes or paths in the domain
  • Subdomains are not automatically included in the association

For iOS Apple App Site Association:​

  • The file must be served without a file extension
  • The MIME type must be application/json
  • The file must be accessible via HTTPS
  • The file must be served directly (not redirected)
  • If you have a robots.txt, ensure it allows access to /.well-known/apple-app-site-association
  • Your server should allow HTTP/2 for optimal performance

Troubleshooting​

Common Issues​

Android Issues​

  1. Passkeys Not Working

    • Ensure your assetlinks.json file is accessible via HTTPS
    • Verify the SHA-256 fingerprint matches your app's signing certificate
    • Check that the package name matches your Android app exactly
    • Confirm the domain matches exactly what's specified in your passkey requests

  2. ProGuard Issues

    • Make sure the ProGuard rules are properly added
    • Clean and rebuild your project after adding the rules

  3. Google Sign-In Failed [Error: no credentials available]

    • This error typically occurs when attempting to use Google Sign-In on an emulator without any Google accounts configured
    • To resolve this:
      • Ensure there is a Google account added to your device or emulator
      • Verify that you have called the signUpWithGoogle() function before calling signIn() with 'google-signin' as an option
      • If testing on an emulator, consider using a physical device with Google accounts properly set up

iOS Issues​

  1. Passkeys Not Working on iOS

    • Verify your Associated Domains capability is properly configured
    • Ensure your AASA file is correctly set up and accessible
    • Check that the domain in your passkey requests matches your associated domain
    • Confirm you're using iOS 16.0+ for testing

  2. Apple Sign In Not Working

    • Verify the Sign In with Apple capability is added to your app
    • Ensure your Apple Developer account has Sign In with Apple enabled for your App ID
    • Check for any error messages in the Xcode console

Validation Tools​

  1. Android Asset Links Validator:

  2. Apple App Site Association Validator:

Build Errors​

If you encounter build errors:

  • Ensure you're using compatible versions of React Native and other dependencies

  • Clean the project and rebuild:

    # For Android
    cd android && ./gradlew clean

    # For iOS
    cd ios && pod install

For additional help, please check the GitHub issues or create a new issue if you encounter any problems.