-
Notifications
You must be signed in to change notification settings - Fork 535
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
aadba8e
commit 47aba5d
Showing
3 changed files
with
145 additions
and
138 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,36 +9,43 @@ The `useSSO()` hook is used to create a new SSO flow. It can be used in both web | |
|
||
<Properties> | ||
- `strategy` | ||
- [`OAuthStrategy`](/docs/references/javascript/types/oauth#o-auth-strategy) | ||
- [`EnterpriseSSOStrategy`](/docs/references/javascript/types/oauth#o-auth-strategy) | ||
|
||
The strategy corresponding to the SSO provider. For example: `oauth_facebook`, `oauth_github`, `enterprise_sso`, etc. | ||
- [`OAuthStrategy`](/docs/references/javascript/types/sso#o-auth-strategy) | ||
|
||
--- | ||
- [`EnterpriseSSOStrategy`](/docs/references/javascript/types/sso#enterprise-sso-strategy) | ||
|
||
- `redirectUrl?` | ||
- `string` | ||
- `strategy?` | ||
|
||
The URL or path to redirect to after the SSO flow is complete. | ||
- `string` | ||
|
||
--- | ||
Select the SSO strategy. The `enterprise_sso` value depends on the object's `identifier` value. Possible `strategy` values are: | ||
|
||
- `unsafeMetadata?` | ||
- [`SignUpUnsafeMetadata`](/docs/references/javascript/types/metadata#sign-up-unsafe-metadata) | ||
- `oauth_<provider>`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). | ||
- `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. | ||
|
||
--- | ||
|
||
Unsafe metadata to be passed to the SSO provider. | ||
- `redirectUrl?` | ||
- `string` | ||
|
||
The URL or path to redirect to after the SSO flow is complete. | ||
|
||
--- | ||
|
||
- `unsafeMetadata?` | ||
- [`SignUpUnsafeMetadata`](/docs/references/javascript/types/metadata#sign-up-unsafe-metadata) | ||
|
||
Unsafe metadata to be passed to the SSO provider. | ||
</Properties> | ||
|
||
## Returns | ||
|
||
The `useSSO()` hook returns the `startFlow()` method, which you can use to initiate the SSO flow. | ||
|
||
The `startFlow()` method has the following signature: | ||
The `startSSOFlow()` method has the following signature: | ||
|
||
```ts | ||
const startFlow: ( | ||
startSSOFlowParams?: StartSSOFlowParams, | ||
) => Promise<StartSSOFlowReturnType> | ||
const startSSOFlow: (startSSOFlowParams?: StartSSOFlowParams) => Promise<StartSSOFlowReturnType> | ||
``` | ||
It accepts the following parameters (`StartSSOFlowParams`): | ||
|
@@ -57,12 +64,131 @@ It accepts the following parameters (`StartSSOFlowParams`): | |
Unsafe metadata to be passed to the OAuth provider. | ||
--- | ||
- `identifier?` | ||
- string | ||
The [identifier](/docs/authentication/configuration/sign-up-sign-in-options#identifier) of the user. | ||
The [identifier](/docs/authentication/configuration/sign-up-sign-in-options#identifier) of the user. Required for `enterprise_sso` strategy. | ||
</Properties> | ||
## How to use the `useSSO()` hook | ||
<Include src="_partials/expo/sso-custom-flow" /> | ||
## How to use `useSSO()` | ||
<Tabs items={["With OAuth", "With SAML"]}> | ||
<Tab> | ||
The following example demonstrates how to create a custom SSO sign-in flow for [Google accounts](/docs/authentication/social-connections/google). | ||
```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }} | ||
import React from 'react' | ||
import * as WebBrowser from 'expo-web-browser' | ||
import { Text, View, Button } from 'react-native' | ||
import { Link } from 'expo-router' | ||
import { useSSO } from '@clerk/clerk-expo' | ||
import * as Linking from 'expo-linking' | ||
|
||
export const useWarmUpBrowser = () => { | ||
React.useEffect(() => { | ||
// Warm up the android browser to improve UX | ||
// https://docs.expo.dev/guides/authentication/#improving-user-experience | ||
void WebBrowser.warmUpAsync() | ||
return () => { | ||
void WebBrowser.coolDownAsync() | ||
} | ||
}, []) | ||
} | ||
|
||
WebBrowser.maybeCompleteAuthSession() | ||
|
||
export default function Page() { | ||
useWarmUpBrowser() | ||
|
||
const { startFlow } = useSSO({ strategy: 'oauth_google' }) | ||
|
||
const onPress = React.useCallback(async () => { | ||
try { | ||
const { createdSessionId, signIn, signUp, setActive } = await startFlow({ | ||
redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }), | ||
}) | ||
|
||
// If sign in was successful, set the active session | ||
if (createdSessionId) { | ||
setActive!({ session: createdSessionId }) | ||
} else { | ||
// Use signIn or signUp returned from startOAuthFlow | ||
// for next steps, such as MFA | ||
} | ||
} catch (err) { | ||
// See https://clerk.com/docs/custom-flows/error-handling | ||
// for more info on error handling | ||
console.error(JSON.stringify(err, null, 2)) | ||
} | ||
}, []) | ||
|
||
return ( | ||
<View> | ||
<Button title="Sign in with Google" onPress={onPress} /> | ||
</View> | ||
) | ||
} | ||
``` | ||
</Tab> | ||
<Tab> | ||
The following example demonstrates how to create a custom SSO sign-in flow with [SAML](/authentication/enterprise-connections/overview#saml). | ||
```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }} | ||
import React from 'react' | ||
import * as WebBrowser from 'expo-web-browser' | ||
import { Text, View, Button } from 'react-native' | ||
import { Link } from 'expo-router' | ||
import { useSSO } from '@clerk/clerk-expo' | ||
import * as Linking from 'expo-linking' | ||
|
||
export const useWarmUpBrowser = () => { | ||
React.useEffect(() => { | ||
// Warm up the android browser to improve UX | ||
// https://docs.expo.dev/guides/authentication/#improving-user-experience | ||
void WebBrowser.warmUpAsync() | ||
return () => { | ||
void WebBrowser.coolDownAsync() | ||
} | ||
}, []) | ||
} | ||
|
||
WebBrowser.maybeCompleteAuthSession() | ||
|
||
export default function Page() { | ||
useWarmUpBrowser() | ||
|
||
const { startFlow } = useSSO({ strategy: 'enterprise_sso' }) | ||
|
||
const onPress = React.useCallback(async () => { | ||
try { | ||
const { createdSessionId, signIn, signUp, setActive } = await startFlow({ | ||
redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }), | ||
// User identifier with a email domain that matches a enterprise connection | ||
identifier: '[email protected]', | ||
}) | ||
|
||
// If sign in was successful, set the active session | ||
if (createdSessionId) { | ||
setActive!({ session: createdSessionId }) | ||
} else { | ||
// Use signIn or signUp returned from startOAuthFlow | ||
// for next steps, such as MFA | ||
} | ||
} catch (err) { | ||
// See https://clerk.com/docs/custom-flows/error-handling | ||
// for more info on error handling | ||
console.error(JSON.stringify(err, null, 2)) | ||
} | ||
}, []) | ||
|
||
return ( | ||
<View> | ||
<Button title="Sign in with Google" onPress={onPress} /> | ||
</View> | ||
) | ||
} | ||
``` | ||
</Tab> | ||
</Tabs> |