worldcoin · andy-t-wang · Dec 1, 2024 · Dec 1, 2024
diff --git a/src/components/Navigation.tsx b/src/components/Navigation.tsx
@@ -193,7 +193,8 @@ export const worldIdNavigation = [
 	{
 		title: 'Sign In with World ID',
 		links: [
-			{ title: 'OpenID Connect (OIDC)', href: '/world-id/sign-in' },
+			{ title: 'Overview', href: '/world-id/sign-in' },
+			{ title: 'OpenID Connect (OIDC)', href: '/world-id/sign-in/oidc' },
 			{ title: 'Common Pitfalls', href: '/world-id/sign-in/pitfalls' },
 		],
 	},

diff --git a/src/pages/world-id/sign-in/index.mdx b/src/pages/world-id/sign-in/index.mdx
@@ -1,108 +1,11 @@
 import { Link } from '@/components/Link'
 
-# Sign in with World ID
+# Overview
 
-<Note type="warning">
-It is <b>strongly recommended</b> that mobile applications use <Link href="/world-id/id/cloud">Incognito Actions</Link> instead. Mobile sign currently behaves poorly.
-</Note>
-When using Sign in with World ID, we highly recommend allowing users to set a separate recovery method for their account
-(e.g. email), in case users lose access to or reset their World ID. Read about World ID Reset [here](/world-id/further-reading/world-id-reset). 
+In almost all situations you should use <Link href="/world-id/id/cloud">Verify</Link> instead of Sign in. 
+Sign In with World ID creates new users accounts and you should only use if if you don't plan to collect
+any additional information. Furthermore, if you are building a native application, you will need to use a third party
+OIDC implementation which has behavior that we cannot control. Thus it is advised for you to use <Link href="/world-id/id/libraries">IDKit</Link>. 
 
-Some helpful resources for integrating World ID with your app:
-
--   World ID [Auth0 Integration](https://world.org/auth0).
--   [NextAuth.js Template Repository](https://github.com/worldcoin/world-id-nextauth-template).
-
-<Note>
-	Typical OIDC-compatible authentication engines include [Auth0](https://auth0.com/), [AWS
-	Cognito](https://aws.amazon.com/cognito/), [CloudFlare
-	Access](https://www.cloudflare.com/products/zero-trust/access/), [OneLogin](https://www.onelogin.com/) and many
-	more. Most languages and frameworks have simple open source packages for this.
-</Note>
-
-<Tabs>
-    <TabItem label="Auth0 Integration">
-        Follow the [Auth0 Integration](https://world.org/auth0) installation instructions to add Sign in with World ID to your Auth0 Tenant using the Client ID and Client Secret found in the [Developer Portal](https://developer.worldcoin.org).
-        <Note>
-            If your app hasn't yet integrated Auth0, you can use any of their [various SDK libraries](https://auth0.com/docs/libraries) to get started. This allows using Sign in with World ID on a very broad range of platforms, including web, mobile, and desktop apps.
-        </Note>
-    </TabItem>
-    <TabItem label="NextAuth Template">
-        1. Create a new repository from our [World ID NextAuth Template Repository](https://github.com/worldcoin/world-id-nextauth-template).
-        2. Rename `.env.example` to `.env.local`, and add your Client ID and Client Secret to the `.env.local` file in your new repository. You can find these in the [Developer Portal](https://developer.worldcoin.org).
-        3. Add the app's URL to the list of allowed redirect URIs in the [Developer Portal](https://developer.worldcoin.org). For example, if your app is hosted at `https://example.com`, add `https://example.com/api/auth/callback/worldcoin` to the list of allowed redirect URIs.
-        <Note>
-            You must use a Staging App to use `localhost` as part of a redirect URI. For this example, you'd use `http://localhost:3000/api/auth/callback/worldcoin` as the redirect URI.
-        </Note>
-        4. Run `pnpm i && pnpm dev` to install dependencies and run the app locally, or deploy the app to [Vercel](https://vercel.com).
-    </TabItem>
-    <TabItem label="Custom Authentication Engines">
-      <Note type="warning">
-        If you don't have an authentication engine, you can implement OIDC flows yourself. See the [OIDC Explainer](/world-id/further-reading/oidc) and [Sign In Reference](/world-id/reference/sign-in) for details.
-      </Note>
-
-      Configure your OIDC authentication engine to use World ID as an Identity Provider (IdP), you will need the following information:
-
-      - **Discovery endpoint**: `https://id.worldcoin.org/.well-known/openid-configuration` (if supported by your OIDC client engine, this will set everything automatically, continue below otherwise)
-
-      ### Required inputs
-
-      - **Client ID**: your app id from the Developer Portal (e.g. {/* cSpell:disable */}`app_GBkZ1KlVUdFTjeMXskrX`{/* cSpell:enable */}).
-      - **Client secret**: app secret, obtained from the "Sign In" tab in the Developer Portal (e.g. `sk_6f07e1566ee4b765fe23d8c8`).
-      - **Authorize endpoint**: `https://id.worldcoin.org/authorize`
-      - **Scope**: must contain `openid`, and may contain two optional scopes for compatibility with applications that require them:
-        - `profile` to receive dummy name information about the user
-        - `email` to receive dummy email information about the user
-      - **Response type**: depends on how you want to authenticate, follow the recommendations of your engine. We recommend authorization code flow for server-side apps and implicit flow for client-side apps.
-        - `code` for authorization code flow
-        - `id_token` (recommended) for implicit flow (ensure your authentication engine provides and validates a `nonce` when using the implicit flow)
-        - `id_token token` or `code token` for hybrid flow. Generally not recommended for Sign in with World ID.
-
-      <Note>
-        We use the same JWT token as the `id_token` and `access_token`. There are no actions or information accessible with the `access_token` that are not contained within the `id_token`, as Sign in with World ID is intended only for authentication and not authorization.
-
-        We do not recommend using the hybrid OIDC flow for this reason.
-      </Note>
-
-      ### Optional inputs
-
-      - **(Not required for implicit flow). Token endpoint**: `https://id.worldcoin.org/token`
-      - **(Only used for hybrid flow). User info endpoint**: `https://id.worldcoin.org/userinfo`
-      - **(Only used for hybrid flow). Introspect endpoint**: `https://id.worldcoin.org/introspect`
-
-      Once you have configured this, you can start the authentication flow from your app or authentication engine.
-    </TabItem>
-
-</Tabs>
-
-## Mapping User Info
-
-<Note>The `https://id.worldcoin.org/beta` claim has been deprecated and replaced by `https://id.worldcoin.org/v1`.</Note>
-
-The `/userinfo` endpoint or `id_token` JWT returns a JSON object with the following fields:
-
-```json {{ title: "Response" }}
-{
-	"sub": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535",
-	"https://id.worldcoin.org/beta": { // deprecated, will be removed in the future
-		"likely_human": "strong",
-		"credential_type": "orb"
-	},
-    "https://id.worldcoin.org/v1": {
-        "verification_level": "orb", // "orb" or "device"
-    },
-	"email": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535@id.worldcoin.org", // if `email` scope is included
-	"name": "World ID User", // if `profile` scope is included
-	"given_name": "World ID", // if `profile` scope is included
-	"family_name": "User" // if `profile` scope is included
-}
-```
-
-<Note type="warning">
-	The `email` field is set only for compatibility with apps that cannot function without it. Users cannot receive
-	emails at this address, and it should be ignored when possible.
-</Note>
-
-The `sub` field is the user's nullifier hash -- their unique identifier in the context of your app. A user's nullifier hash will be different for each app they use.
-
-You can information about a user's World ID Credentials in the `https://id.worldcoin.org/v1` object. Use the `verification_level` field to determine whether the user has been Orb-verified or not.
+It is optimal to use cloud verification. The flow that we suggest is to use your existing login and then
+allow users to verify their uniqueness on their existing account using <Link href="/world-id/id/cloud">Verify</Link> 
diff --git a/src/pages/world-id/sign-in/oidc.mdx b/src/pages/world-id/sign-in/oidc.mdx
@@ -0,0 +1,100 @@
+import { Link } from '@/components/Link'
+
+# Sign in with World ID
+
+-   World ID [Auth0 Integration](https://world.org/auth0).
+-   [NextAuth.js Template Repository](https://github.com/worldcoin/world-id-nextauth-template).
+
+<Note>
+	Typical OIDC-compatible authentication engines include [Auth0](https://auth0.com/), [AWS
+	Cognito](https://aws.amazon.com/cognito/), [CloudFlare
+	Access](https://www.cloudflare.com/products/zero-trust/access/), [OneLogin](https://www.onelogin.com/) and many
+	more. Most languages and frameworks have simple open source packages for this.
+</Note>
+
+<Tabs>
+    <TabItem label="Auth0 Integration">
+        Follow the [Auth0 Integration](https://world.org/auth0) installation instructions to add Sign in with World ID to your Auth0 Tenant using the Client ID and Client Secret found in the [Developer Portal](https://developer.worldcoin.org).
+        <Note>
+            If your app hasn't yet integrated Auth0, you can use any of their [various SDK libraries](https://auth0.com/docs/libraries) to get started. This allows using Sign in with World ID on a very broad range of platforms, including web, mobile, and desktop apps.
+        </Note>
+    </TabItem>
+    <TabItem label="NextAuth Template">
+        1. Create a new repository from our [World ID NextAuth Template Repository](https://github.com/worldcoin/world-id-nextauth-template).
+        2. Rename `.env.example` to `.env.local`, and add your Client ID and Client Secret to the `.env.local` file in your new repository. You can find these in the [Developer Portal](https://developer.worldcoin.org).
+        3. Add the app's URL to the list of allowed redirect URIs in the [Developer Portal](https://developer.worldcoin.org). For example, if your app is hosted at `https://example.com`, add `https://example.com/api/auth/callback/worldcoin` to the list of allowed redirect URIs.
+        <Note>
+            You must use a Staging App to use `localhost` as part of a redirect URI. For this example, you'd use `http://localhost:3000/api/auth/callback/worldcoin` as the redirect URI.
+        </Note>
+        4. Run `pnpm i && pnpm dev` to install dependencies and run the app locally, or deploy the app to [Vercel](https://vercel.com).
+    </TabItem>
+    <TabItem label="Custom Authentication Engines">
+      <Note type="warning">
+        If you don't have an authentication engine, you can implement OIDC flows yourself. See the [OIDC Explainer](/world-id/further-reading/oidc) and [Sign In Reference](/world-id/reference/sign-in) for details.
+      </Note>
+
+      Configure your OIDC authentication engine to use World ID as an Identity Provider (IdP), you will need the following information:
+
+      - **Discovery endpoint**: `https://id.worldcoin.org/.well-known/openid-configuration` (if supported by your OIDC client engine, this will set everything automatically, continue below otherwise)
+
+      ### Required inputs
+
+      - **Client ID**: your app id from the Developer Portal (e.g. {/* cSpell:disable */}`app_GBkZ1KlVUdFTjeMXskrX`{/* cSpell:enable */}).
+      - **Client secret**: app secret, obtained from the "Sign In" tab in the Developer Portal (e.g. `sk_6f07e1566ee4b765fe23d8c8`).
+      - **Authorize endpoint**: `https://id.worldcoin.org/authorize`
+      - **Scope**: must contain `openid`, and may contain two optional scopes for compatibility with applications that require them:
+        - `profile` to receive dummy name information about the user
+        - `email` to receive dummy email information about the user
+      - **Response type**: depends on how you want to authenticate, follow the recommendations of your engine. We recommend authorization code flow for server-side apps and implicit flow for client-side apps.
+        - `code` for authorization code flow
+        - `id_token` (recommended) for implicit flow (ensure your authentication engine provides and validates a `nonce` when using the implicit flow)
+        - `id_token token` or `code token` for hybrid flow. Generally not recommended for Sign in with World ID.
+
+      <Note>
+        We use the same JWT token as the `id_token` and `access_token`. There are no actions or information accessible with the `access_token` that are not contained within the `id_token`, as Sign in with World ID is intended only for authentication and not authorization.
+
+        We do not recommend using the hybrid OIDC flow for this reason.
+      </Note>
+
+      ### Optional inputs
+
+      - **(Not required for implicit flow). Token endpoint**: `https://id.worldcoin.org/token`
+      - **(Only used for hybrid flow). User info endpoint**: `https://id.worldcoin.org/userinfo`
+      - **(Only used for hybrid flow). Introspect endpoint**: `https://id.worldcoin.org/introspect`
+
+      Once you have configured this, you can start the authentication flow from your app or authentication engine.
+    </TabItem>
+
+</Tabs>
+
+## Mapping User Info
+
+<Note>The `https://id.worldcoin.org/beta` claim has been deprecated and replaced by `https://id.worldcoin.org/v1`.</Note>
+
+The `/userinfo` endpoint or `id_token` JWT returns a JSON object with the following fields:
+
+```json {{ title: "Response" }}
+{
+	"sub": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535",
+	"https://id.worldcoin.org/beta": { // deprecated, will be removed in the future
+		"likely_human": "strong",
+		"credential_type": "orb"
+	},
+    "https://id.worldcoin.org/v1": {
+        "verification_level": "orb", // "orb" or "device"
+    },
+	"email": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535@id.worldcoin.org", // if `email` scope is included
+	"name": "World ID User", // if `profile` scope is included
+	"given_name": "World ID", // if `profile` scope is included
+	"family_name": "User" // if `profile` scope is included
+}
+```
+
+<Note type="warning">
+	The `email` field is set only for compatibility with apps that cannot function without it. Users cannot receive
+	emails at this address, and it should be ignored when possible.
+</Note>
+
+The `sub` field is the user's nullifier hash -- their unique identifier in the context of your app. A user's nullifier hash will be different for each app they use.
+
+You can information about a user's World ID Credentials in the `https://id.worldcoin.org/v1` object. Use the `verification_level` field to determine whether the user has been Orb-verified or not.