Skip to content

Commit

Permalink
docs review
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexisintech
alexisintech committed Feb 5, 2025
1 parent facae1f commit 7bf11d2
Show file tree
Hide file tree
Showing 3 changed files with 126 additions and 134 deletions.
2 changes: 0 additions & 2 deletions docs/authentication/configuration/sign-up-sign-in-options.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,6 @@ A passkey is a type of sign-in credential that requires one user action, but use
1. A pin number or biometric data
1. A physical device

Passkeys are the most secure **passwordless** strategy because they use two factors.

Users can only create passkeys after signing up, so you'll need to enable another authentication strategy for the sign-up process. After signing in, users can create a passkey.

#### Manage user passkeys
Expand Down
34 changes: 18 additions & 16 deletions docs/custom-flows/passkeys.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ description: Learn how to use the Clerk API to build a custom authentication flo

<Include src="_partials/custom-flows-callout" />

Clerk supports passwordless authentication via passkeys, enabling users to sign in without having to remember a password. Instead, users select a passkey associated with their device, which they can use to authenticate themselves.
Clerk supports passwordless authentication via [passkeys](/docs/authentication/configuration/sign-up-sign-in-options#passkeys), enabling users to sign in without having to remember a password. Instead, users select a passkey associated with their device, which they can use to authenticate themselves.

This guide will walk you through how to use the Clerk API to build custom flows for creating, signing users in with, and managing passkeys.
This guide demonstrates how to use the Clerk API to build a custom user interface for creating, signing users in with, and managing passkeys.

## Enable passkeys

Expand All @@ -32,16 +32,15 @@ export function CreatePasskeyButton() {
if (!user) return

try {
const response = await user?.createPasskey()
console.log(response)
await user?.createPasskey()
} catch (err) {
// See https://clerk.com/docs/custom-flows/error-handling
// for more info on error handling
console.error('Error:', JSON.stringify(err, null, 2))
}
}

return <button onClick={createClerkPasskey}>Create a passkey now</button>
return <button onClick={createClerkPasskey}>Create a passkey</button>
}
```

Expand All @@ -56,7 +55,7 @@ export function SignInWithPasskeyButton() {

const signInWithPasskey = async () => {
// 'discoverable' lets the user choose a passkey
// without autofilling any of the options
// without auto-filling any of the options
try {
const signInAttempt = await signIn?.authenticateWithPasskey({
flow: 'discoverable',
Expand Down Expand Up @@ -90,20 +89,22 @@ To rename a user's passkey in your Clerk app, you must call the [`update()`](/do
```tsx {{ filename: 'components/RenamePasskeyUI.tsx' }}
export function RenamePasskeyUI() {
const { user } = useUser()
const { passkeys } = user

const passkeyToUpdateId = useRef<HTMLInputElement>(null)
const newPasskeyName = useRef<HTMLInputElement>(null)
const { passkeys } = user
const [success, setSuccess] = useState(false)

const renamePasskey = async () => {
try {
const passkeyToUpdate = passkeys?.find(
(pk: PasskeyResource) => pk.id === passkeyToUpdateId.current?.value,
)
const response = await passkeyToUpdate?.update({

await passkeyToUpdate?.update({
name: newPasskeyName.current?.value,
})
console.log(response)

setSuccess(true)
} catch (err) {
// See https://clerk.com/docs/custom-flows/error-handling
Expand All @@ -125,9 +126,9 @@ export function RenamePasskeyUI() {
)
})}
</ul>
<input ref={passkeyToUpdateId} type="text" placeholder="ID of passkey to update" />
<input type="text" placeholder="New name" ref={newPasskeyName} />
<button onClick={renamePasskey}>Rename your passkey</button>
<input ref={passkeyToUpdateId} type="text" placeholder="Enter the passkey ID" />
<input type="text" placeholder="Enter the passkey's new name" ref={newPasskeyName} />
<button onClick={renamePasskey}>Rename passkey</button>
<p>Passkey updated: {success ? 'Yes' : 'No'}</p>
</>
)
Expand All @@ -141,15 +142,16 @@ To delete a user's passkey from your Clerk app, you must call the [`delete()`](/
```tsx {{ filename: 'components/DeletePasskeyUI.tsx' }}
export function DeletePasskeyUI() {
const { user } = useUser()
const passkeyToDeleteId = useRef<HTMLInputElement>(null)
const { passkeys } = user

const passkeyToDeleteId = useRef<HTMLInputElement>(null)
const [success, setSuccess] = useState(false)

const deletePasskey = async () => {
const passkeyToDelete = passkeys?.find((pk: any) => pk.id === passkeyToDeleteId.current?.value)
try {
const response = await passkeyToDelete?.delete()
console.log(response)
await passkeyToDelete?.delete()

setSuccess(true)
} catch (err) {
// See https://clerk.com/docs/custom-flows/error-handling
Expand All @@ -171,7 +173,7 @@ export function DeletePasskeyUI() {
)
})}
</ul>
<input ref={passkeyToDeleteId} type="text" placeholder="ID of passkey to delete" />
<input ref={passkeyToDeleteId} type="text" placeholder="Enter the passkey ID" />
<button onClick={deletePasskey}>Delete passkey</button>
<p>Passkey deleted: {success ? 'Yes' : 'No'}</p>
</>
Expand Down
224 changes: 108 additions & 116 deletions docs/references/expo/passkeys.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,152 +3,144 @@ title: Configure passkeys for Expo
description: Learn how to configure passkeys for your Expo application.
---

This guide shows you how to configure passkeys for your Expo application.
[Passkeys](/docs/authentication/configuration/sign-up-sign-in-options#passkeys) are a secure, passwordless authentication method that use biometrics and a physical device to authenticate users. This guide shows you how to configure passkeys for your Expo application.

> [!WARNING]
> This API is available only for [@clerk/clerk-expo v2](/docs/upgrade-guides/expo-v2/upgrade) >=2.2.0.
## Configuration
> This API is available only for [`@clerk/clerk-expo >=2.2.0`](/docs/upgrade-guides/expo-v2/upgrade).
<Steps>
### Enable passkeys
## Enable passkeys

To use passkeys, first enable the strategy in the Clerk Dashboard.

1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username).
1. In the navigation sidebar, select **User & Authentication > Email, Phone, and Username**.
1. In the **Authentication strategies** section of this page, ensure **Passkeys** is enabled.
1. In the Clerk Dashboard, navigate to the [**Email, Phone, Username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page.
1. In the **Authentication strategies** section, enable **Passkeys**.

### Configure passkeys for iOS and Android
## Configure passkeys

Use the following tabs to configure your passkeys for `iOS` or `Android`.

<Tabs items={['iOS', 'Android']}>
<Tab>
<Steps>
> [!WARNING]
> iOS supports passkeys from version iOS 16+
>
> This library includes native code and will not work when running expo go. Instead use a development build by running `npx expo run:ios`.
> [!WARNING]
> iOS supports passkeys from version iOS 16+
>
> This library includes native code and will not work when running Expo Go. Instead, use a development build by running `npx expo run:ios`.
### Get your App ID Prefix and Bundle ID from Apple
## Get your App ID Prefix and Bundle ID from Apple

To get your **App ID Prefix** and **Bundle ID**, follow these steps:
To get your **App ID Prefix** and **Bundle ID**, follow these steps:

1. Navigate to the [Apple Developer dashboard](https://developer.apple.com/account).
1. Under **Certificates, IDs and Profiles**, select [**Identifiers**](https://developer.apple.com/account/resources/identifiers/list).
1. In the top-right, select the dropdown and select **App IDs**.
1. Select the **App ID** you want to configure passkeys for. You'll be redirect to the **Edit your App ID Configuration** page.
1. At the top of the page, you'll see your **App ID Prefix** and **Bundle ID**. Save these values somewhere secure.
1. Navigate to the [Apple Developer dashboard](https://developer.apple.com/account).
1. Under **Certificates, IDs and Profiles**, select [**Identifiers**](https://developer.apple.com/account/resources/identifiers/list).
1. In the top-right, select the dropdown and select **App IDs**.
1. Select the **App ID** you want to configure passkeys for. You'll be redirect to the **Review your App ID Configuration** page.
1. At the top of the page, you'll see your **App ID Prefix** and **Bundle ID**. Save these values somewhere secure.

### Set up your associated domain file in the Clerk Dashboard
## Set up your associated domain file in the Clerk Dashboard

1. In the Clerk Dashboard, navigate to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page.
1. Select the **iOS** tab.
1. Fill out the form with the following information:
- Your iOS app's **App ID Prefix (Team ID)**
- Your iOS app's **Bundle ID**
1. Look for the text that says "Frontend API" followed by a URL. This URL is your Clerk **Frontend API URL** - copy it as you'll need it in the next step.
1. In the Clerk Dashboard, navigate to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page.
1. Select the **iOS** tab.
1. Select **Add iOS App**.
1. Paste the **App ID Prefix** and **Bundle ID** that you copied in the previous step.
1. Select **Add App**.
1. On the right-side, save your **Frontend API URL** somewhere secure.

### Update `app.json` in your Expo app
## Update `app.json` in your Expo app

1. In your app's `app.json` file, under the `ios` object, add the `associatedDomains` property as shown in the following example. Replace `<YOUR_FRONTEND_API>` with the value that you copied in the previous step.
1. In your app's `app.json` file, under the `ios` object, add the `associatedDomains` property as shown in the following example. Replace `<YOUR_FRONTEND_API_URL>` with the **Frontend API URL** value that you saved in the previous step.

```json {{ filename: 'app.json', mark: [[5, 12], [14, 20]] }}
{
"expo": {
//...existing properties
"plugins": [
[
"expo-build-properties",
{
"ios": {
"deploymentTarget": "16.0" // iOS Support passkeys from version iOS 16+
}
```json {{ filename: 'app.json', mark: [[5, 12], [14, 20]] }}
{
"expo": {
//...existing properties
"plugins": [
[
"expo-build-properties",
{
"ios": {
"deploymentTarget": "16.0" // iOS Support passkeys from version iOS 16+
}
]
],
"ios": {
//...existing properties
"associatedDomains": [
"applinks:<YOUR_FRONTEND_API_URL>",
"webcredentials:<YOUR_FRONTEND_API_URL>"
]
}
}
]
],
"ios": {
//...existing properties
"associatedDomains": [
"applinks:<YOUR_FRONTEND_API_URL>",
"webcredentials:<YOUR_FRONTEND_API_URL>"
]
}
}
```
</Steps>
}
```
</Tab>

<Tab>
<Steps>
> [!WARNING]
> Android supports passkeys from version 9+
>
> This library includes native code and will not work when running expo go. Instead use a development build by running `npx expo run:android`. ([**ref**](https://docs.expo.dev/workflow/customizing/#using-libraries-that-include-native-code))
>
> Passkeys can't work with android emulators. You need to use a physical device to test passkeys.
### Set up your Android app links in the Clerk Dashboard

1. In the Clerk Dashboard, navigate to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page.
1. Select the **Android** tab.
1. Fill out the form with the following information:
- The `namespace` (use the default value: `android_app`)
- Your Android app's package name
- The `SHA256 certificate fingerprints`. If you don't know where to find the `SHA256 certificate fingerprints`, see the [Expo docs](https://docs.expo.dev/linking/android-app-links/#create-assetlinksjson-file).
1. After submitting the form, you can verify that your `assetlinks.json` file is properly associated with your app by using [Google's **Statement List Generator and Tester**](https://developers.google.com/digital-asset-links/tools/generator).
1. Look for the text that says "Frontend API" followed by a URL. This URL is your Clerk **Frontend API URL** - copy it as you'll need it in the next step.

### Install `expo-build-properties` in your Expo application

<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
```bash {{ filename: 'terminal' }}
npm install expo-build-properties
```

```bash {{ filename: 'terminal' }}
yarn add expo-build-properties
```

```bash {{ filename: 'terminal' }}
pnpm add expo-build-properties
```
</CodeBlockTabs>

### Update `app.json` in your Expo application

1. In your app's `app.json` file, under `android`, add the `intentFilters` property as shown in the following example. Replace `<YOUR_FRONTEND_API>` with the value that you copied in the previous step.

```json {{ filename: 'app.json', mark: [[3, 6], [10, 22]] }}
{
"expo": {
"plugins": [["expo-build-properties"]],
"android": {
//...existing properties
"intentFilters": [
{
"action": "VIEW",
"autoVerify": true,
"data": [
{
"scheme": "https",
"host": "<YOUR_FRONTEND_API>"
}
],
"category": ["BROWSABLE", "DEFAULT"]
}
]
}
> [!WARNING]
> Android supports passkeys from version 9+. Passkeys will not work with Android emulators. You must use a physical device.
>
> This library includes native code and [will not work when running Expo Go](https://docs.expo.dev/workflow/customizing/#using-libraries-that-include-native-code). Instead, use a development build by running `npx expo run:android`.
## Set up your Android app links in the Clerk Dashboard

1. In the Clerk Dashboard, navigate to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page.
1. Select the **Android** tab.
1. Select **Add Android app**.
1. Fill out the form with the following information:
- The `namespace` (This guide uses the default value: `android_app`)
- Your Android app's package name
- The `SHA256 certificate fingerprints`. If you don't know where to find the `SHA256 certificate fingerprints`, see the [Expo docs](https://docs.expo.dev/linking/android-app-links/#create-assetlinksjson-file).
1. After submitting the form, you can verify that your `assetlinks.json` file is properly associated with your app by using [Google's **Statement List Generator and Tester**](https://developers.google.com/digital-asset-links/tools/generator).
1. On the right-side, save your **Frontend API URL** somewhere secure.

## Install `expo-build-properties` in your Expo application

<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
```bash {{ filename: 'terminal' }}
npm install expo-build-properties
```

```bash {{ filename: 'terminal' }}
yarn add expo-build-properties
```

```bash {{ filename: 'terminal' }}
pnpm add expo-build-properties
```
</CodeBlockTabs>

## Update `app.json` in your Expo application

1. In your app's `app.json` file, under `android`, add the `intentFilters` property as shown in the following example. Replace `<YOUR_FRONTEND_API_URL>` with the **Frontend API URL** value that you saved in the previous step.

```json {{ filename: 'app.json', mark: [[3, 6], [10, 22]] }}
{
"expo": {
"plugins": [["expo-build-properties"]],
"android": {
//...existing properties
"intentFilters": [
{
"action": "VIEW",
"autoVerify": true,
"data": [
{
"scheme": "https",
"host": "<YOUR_FRONTEND_API_URL>"
}
],
"category": ["BROWSABLE", "DEFAULT"]
}
]
}
}
```
</Steps>
}
```
</Tab>
</Tabs>

### Install `@clerk/expo-passkeys`
## Install `@clerk/expo-passkeys`

Run the following command to install the `@clerk/expo-passkeys` package:

Expand All @@ -166,15 +158,15 @@ This guide shows you how to configure passkeys for your Expo application.
```
</CodeBlockTabs>

### Prebuild Expo project
## Prebuild Expo project

Run the following command to prebuild your Expo project:

```bash {{ filename: 'terminal' }}
npx expo prebuild
```

### Update your `<ClerkProvider>`
## Update your `<ClerkProvider>`

Pass the `passkeys` object to the `__experimental_passkeys` property of your `<ClerkProvider>` component, as shown in the following example:

Expand Down

0 comments on commit 7bf11d2

Please sign in to comment.