Signing in users with OIDC

This document shows you how to use Identity Platform to sign in users with an OpenID Connect (OIDC) provider.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

6. Enable Identity Platform, and add the Client SDK to your app. See the Quickstart to learn how.

Configuring the provider

1. Go to the Identity Providers page in the Cloud Console.
   Go to the Identity Providers page
   

2. Click Add a Provider, and select OpenID Connect from the list.

Authorization Code Flow

1. Enter the following details to enable the Authorization Code Flow:

   1. Select Code Flow under Choose grant type section.

   2. The Name of the provider. This can be the same as the provider ID, or a custom name. If you enter a custom name, click Edit next to Provider ID to specify the ID (which must begin with oidc.).

   3. The provider's Client ID.

   4. The provider's Issuer. This should look something like https://example.com. Identity Platform uses this URL to locate the OIDC discovery document (typically found at /.well-known/openid-configuration), which specifies the provider's OAuth endpoints and public keys.

      Note: If your OIDC provider doesn't comply with the OIDC specification for discovery, it won't work with Identity Platform.

   5. The provider's Client Secret.

2. Add your app to the list of Authorized Domains. For example, if your app's sign-in URL is https://example.com/login, add example.com.

3. Configure the Identity Platform callback URL as a redirect URL with your OIDC provider. The URL should look similar to https://[PROJECT-ID]/__/auth/handler.

4. Click Save.

Implicit Flow

1. Enter the following details to enable the Implicit Flow:

   1. Select Implicit Flow under Choose grant type section.

   2. The Name of the provider. This can be the same as the provider ID, or a custom name. If you enter a custom name, click Edit next to Provider ID to specify the ID (which must begin with oidc.).

   3. The provider's Client ID.

   4. The provider's Issuer. This should look something like https://example.com. Identity Platform uses this URL to locate the OIDC discovery document (typically found at /.well-known/openid-configuration), which specifies the provider's OAuth endpoints and public keys.

      Note: If your OIDC provider doesn't comply with the OIDC specification for discovery, it won't work with Identity Platform.

2. Add your app to the list of Authorized Domains. For example, if your app's sign-in URL is https://example.com/login, add example.com.

3. Configure the Identity Platform callback URL as a redirect URL with your OIDC provider. The URL should look similar to https://[PROJECT-ID]/__/auth/handler.

4. Click Save.

Signing in users

There are two ways to sign in users with OIDC:

• Using OAuth flow. This way completes the OAuth handshake for you. Based on the Authorization Code Flow/Implicit Flow selection at the configuring provider step, GCIP server chooses the desired flow to communicate with the Identity Provider.

• Using the OIDC provider's ID token. This way assumes you already have an OIDC token available.

Signing in users with OAuth

To sign in using OAuth:

1. Create an OAuthProvider instance with the provider ID you configured in the previous section. The provider ID must start with oidc..

   const provider = new firebase.auth.OAuthProvider('oidc.myProvider');
   

2. Start the sign in flow. You can choose to either use a popup or a redirect.

   Popup

   To show a popup, call signInWithPopup():

   firebase.auth().signInWithPopup(provider)
     .then((result) => {
       // result.credential is a firebase.auth.OAuthCredential object.
       // result.credential.providerId is equal to 'oidc.myProvider'.
       // result.credential.idToken is the OIDC provider's ID token.
     })
     .catch((error) => {
       // Handle error.
     });
   

   Redirect

   To redirect to a sign-in page, call signInWithRedirect():

   firebase.auth().signInWithRedirect(provider)
     .catch((error) => {
       // Handle error.
     });
   

   Then, call getRedirectResult() to get the results when the user returns to your app:

   // On return.
   firebase.auth().getRedirectResult()
     .then((result) => {
       // result.credential is a firebase.auth.OAuthCredential object.
       // result.credential.providerId is equal to 'oidc.myProvider'.
       // result.credential.idToken is the OIDC provider's ID token.
     })
     .catch((error) => {
       // Handle error.
     });
   

At the conclusion of either flow, you can get the OIDC ID token using the result.credential.idToken field.

Signing in users directly

To sign a user in with an OIDC ID token directly:

1. Initialize an OAuthProvider instance with the provider ID you configured in the previous section. The provider ID must start with oidc.. Then, create an OAuthCredential:

   const provider = new firebase.auth.OAuthProvider('oidc.myProvider');
   const credential = provider.credential(oidcIdToken, null);
   

2. Call signInWithCredential() to sign the user in:

   firebase.auth().signInWithCredential(credential)
     .then((result) => {
       // user now has a odic.myProvider UserInfo in providerData.
     })
     .catch((error) => {
       // Handle error.
     });
   

Linking user accounts

If a user has already signed in to your app using a different method (such as email/password), you can link their existing account to the OIDC provider using linkWithPopup() or linkWithRedirect(). For example:

const provider = new firebase.auth.OAuthProvider('oidc.myProvider');

// Link with a popup.
firebase.auth().currentUser.linkWithPopup(provider)
    // currentUser.providerData now has an additional entry for this provider.
  }).catch((error) => {
    // Handle error.
  });

Re-authenticating users

Certain sensitive operations, like updating a user's email or password, require the user to have signed in recently. To sign a user in again, call reauthenticateWithPopup() or reauthenticateWithRedirect(). For example:

const provider = new firebase.auth.OAuthProvider('oidc.myProvider');

// Reauthenticate with a popup.
firebase.auth().currentUser.reauthenticateWithPopup(provider)
  .then((result) => {
    // Get the updated ID token.
    return result.user.getIdTokenResult();
  })
  .then((idTokenResult) => {
    // idTokenResult.authTime should be updated to reflect recent sign-in status.
    // idTokenResult.token has the latest ID token.
  })
  .catch((error) => {
    // Handle error.
  });

What's next

• Signing in users with SAML
• Showing a custom domain during sign in
• Managing OIDC and SAML providers programmatically