feat: complete OIDC support for Apple, Google and others (#690)

Updates the `signInWithIdToken` API:

- No longer experimental.
- Adds optional `access_token` parameter.
- Updates the types on `provider`.
- More docs.

To be merged after release of:
supabase/auth#1108

src/GoTrueClient.ts

@@ -496,22 +496,21 @@ export default class GoTrueClient {
   }
 
   /**
-   * Allows signing in with an ID token issued by certain supported providers.
-   * The ID token is verified for validity and a new session is established.
-   *
-   * @experimental
+   * Allows signing in with an OIDC ID token. The authentication provider used
+   * should be enabled and configured.
    */
   async signInWithIdToken(credentials: SignInWithIdTokenCredentials): Promise<AuthTokenResponse> {
     await this._removeSession()
 
     try {
-      const { options, provider, token, nonce } = credentials
+      const { options, provider, token, access_token, nonce } = credentials
 
       const res = await _request(this.fetch, 'POST', `${this.url}/token?grant_type=id_token`, {
         headers: this.headers,
         body: {
           provider,
           id_token: token,
+          access_token,
           nonce,
           gotrue_meta_security: { captcha_token: options?.captchaToken },
         },

src/lib/types.ts

@@ -494,13 +494,13 @@ export type SignInWithOAuthCredentials = {
 }
 
 export type SignInWithIdTokenCredentials = {
-  /**
-   * Only Apple and Google ID tokens are supported for use from within iOS or Android applications.
-   */
-  provider: 'google' | 'apple'
-  /** ID token issued by Apple or Google. */
+  /** Provider name or OIDC `iss` value identifying which provider should be used to verify the provided token. Supported names: `google`, `apple`, `azure`, `facebook`, `keycloak` (deprecated). */
+  provider: 'google' | 'apple' | 'azure' | 'facebook' | string
+  /** OIDC ID token issued by the specified provider. The `iss` claim in the ID token must match the supplied provider. Some ID tokens contain an `at_hash` which require that you provide an `access_token` value to be accepted properly. If the token contains a `nonce` claim you must supply the nonce used to obtain the ID token. */
   token: string
-  /** If the ID token contains a `nonce`, then the hash of this value is compared to the value in the ID token. */
+  /** If the ID token contains an `at_hash` claim, then the hash of this value is compared to the value in the ID token. */
+  access_token?: string
+  /** If the ID token contains a `nonce` claim, then the hash of this value is compared to the value in the ID token. */
   nonce?: string
   options?: {
     /** Verification token received when the user completes the captcha on the site. */