Why Does Family Search Give Me Oauth2 Error When I Sign in

This document explains how applications installed on devices like phones, tablets, and computers use Google'southward OAuth 2.0 endpoints to authorize access to Google APIs.

OAuth two.0 allows users to share specific data with an awarding while keeping their usernames, passwords, and other data private. For example, an application tin can apply OAuth 2.0 to obtain permission from users to store files in their Google Drives.

Installed apps are distributed to individual devices, and it is assumed that these apps cannot keep secrets. They can admission Google APIs while the user is present at the app or when the app is running in the groundwork.

This authorization catamenia is similar to the one used for web server applications. The main departure is that installed apps must open the organisation browser and supply a local redirect URI to handle responses from Google's authority server.

Alternatives

For mobile apps, you may prefer to use Google Sign-in for Android or iOS. The Google Sign-in client libraries handle hallmark and user authorization, and they may be simpler to implement than the lower-level protocol described here.

For apps running on devices that do not support a system browser or that have limited input capabilities, such equally TVs, game consoles, cameras, or printers, see OAuth 2.0 for TVs & Devices or Sign-In on TVs and Limited Input Devices.

Libraries and samples

Nosotros recommend the post-obit libraries and samples to help you implement the OAuth 2.0 flow described in this document:

• AppAuth for Android library
• AppAuth for iOS library
• OAuth for Apps: Windows Samples

Prerequisites

Enable APIs for your project

Whatsoever application that calls Google APIs needs to enable those APIs in the API Console.

To enable an API for your project:

1. Open the API Library in the Google API Console.
2. If prompted, select a projection, or create a new one.
3. The API Library lists all available APIs, grouped by production family and popularity. If the API you desire to enable isn't visible in the listing, use search to find it, or click View All in the production family information technology belongs to.
4. Select the API you desire to enable, and then click the Enable push button.
5. If prompted, enable billing.
6. If prompted, read and accept the API'due south Terms of Service.

Create authorization credentials

Any awarding that uses OAuth 2.0 to access Google APIs must have authorization credentials that identify the application to Google's OAuth ii.0 server. The post-obit steps explain how to create credentials for your project. Your applications tin can and then utilise the credentials to access APIs that y'all have enabled for that project.

1. Go to the Credentials page.
2. Click Create credentials > OAuth customer ID.
3. The sections below describe the client types and the redirect methods that Google's authorization server supports. Choose the client blazon that is recommended for your application, proper name your OAuth client, and fix the other fields in the grade as advisable.

Custom URI scheme (Android, iOS, UWP)

A custom URI scheme is recommended for Android apps, iOS apps, and Universal Windows Platform (UWP) apps.

Android

1. Select the Android application blazon.
2. Enter a proper noun for the OAuth client. This proper name is displayed on your project'due south Credentials page to identify the client.
3. Enter the package proper noun of your Android app. This value is defined in the package aspect of the <manifest> element in your app manifest file.
4. Enter the SHA-1 signing document fingerprint of the app distribution.
   • If your app uses app signing by Google Play, re-create the SHA-one fingerprint from the app signing page of the Play Console.
   • If you manage your own keystore and signing keys, apply the keytool utility included with Coffee to print certificate data in a human-readable format. Copy the SHA1 value in the Certificate fingerprints section of the keytool output. Run across Authenticating Your Client in the Google APIs for Android documentation for more information.
5. Click Create.

iOS

1. Select the iOS awarding type.
2. Enter a proper name for the OAuth client. This name is displayed on your project's Credentials page to identify the customer.
3. Enter the bundle identifier for your app. The parcel ID is the value of the CFBundleIdentifier primal in your app's information property listing resources file (info.plist). The value is almost commonly displayed in the General pane or the Signing & Capabilities pane of the Xcode project editor. The packet ID is besides displayed in the General Information section of the App Information folio for the app on Apple's App Store Connect site.
4. (Optional)

   Enter your app'southward App Store ID if the app is published in Apple's App Store. The Store ID is a numeric string included in every Apple App Store URL.

   1. Open the Apple App Store app on your iOS or iPadOS device.
   2. Search for your app.
   3. Select the Share button (foursquare and arrow up symbol).
   4. Select Copy Link.
   5. Paste the link into a text editor. The App Store ID is the concluding role of the URL.

      Example: https://apps.apple.com/app/google/id284815942

5. (Optional)

   Enter your Team ID. Come across Locate your Squad ID in the Apple Developer Account documentation for more than information.

6. Click Create.

UWP

1. Select the Universal Windows Platform application type.
2. Enter a name for the OAuth customer. This proper noun is displayed on your project's Credentials page to identify the client.
3. Enter your app'south 12-grapheme Microsoft Store ID. You can find this value in Microsoft Partner Center on the App identity page in the App direction section.
4. Click Create.

For UWP apps, the custom URI scheme cannot be longer than 39 characters.

Loopback IP address (macOS, Linux, Windows desktop)

To receive the dominance code using this URL, your application must be listening on the local web server. That is possible on many, but not all, platforms. However, if your platform supports it, this is the recommended mechanism for obtaining the authorization code.

When your app receives the authorization response, for best usability information technology should respond past displaying an HTML page that instructs the user to close the browser and return to your app.

Recommended usage	macOS, Linux, and Windows desktop (merely non Universal Windows Platform) apps
Form values	Fix the awarding type to Desktop app.

Manual copy/paste

See manual copy/paste details

This redirect method returns the authority code in the HTML page's <title> field and also displays the lawmaking to the user, as shown in the image beneath. The user must and then manually copy and paste the code into your awarding.

Traditionally, apps that used this choice programmatically extracted the authorisation code from the HTML folio. The copy/paste option served as a fallback in case the value could not be parsed.

Recommended usage	Platforms that cannot support an automatic browser redirect via a custom URI scheme or loopback IP accost. Notation that in almost cases where the platform does non accept a usable browser, the OAuth 2.0 for TVs & Devices flow is recommended.
Form values	Set the application type to Desktop app.

Identify access scopes

Scopes enable your application to only asking admission to the resources that it needs while as well enabling users to command the corporeality of access that they grant to your awarding. Thus, there may be an changed relationship between the number of scopes requested and the likelihood of obtaining user consent.

Before you start implementing OAuth 2.0 authorization, we recommend that you lot place the scopes that your app will demand permission to access.

The OAuth 2.0 API Scopes document contains a total list of scopes that you might utilise to access Google APIs.

Obtaining OAuth ii.0 admission tokens

The following steps show how your awarding interacts with Google's OAuth two.0 server to obtain a user's consent to perform an API request on the user'south behalf. Your application must have that consent before it can execute a Google API request that requires user dominance.

Step ane: Generate a lawmaking verifier and claiming

Google supports the Proof Fundamental for Code Exchange (PKCE) protocol to make the installed app menstruum more secure. A unique code verifier is created for every say-so request, and its transformed value, called "code_challenge", is sent to the authorization server to obtain the authorization code.

Create the code verifier

A code_verifier is a high-entropy cryptographic random cord using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

The code verifier should take enough entropy to brand it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

Code Challenge Generation Methods
S256 (recommended)	The code challenge is the Base64URL (with no padding) encoded SHA256 hash of the code verifier. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain	The code challenge is the aforementioned value every bit the code verifier generated above. code_challenge = code_verifier

Step 2: Send a asking to Google'south OAuth ii.0 server

To obtain user authorisation, transport a request to Google's authorization server at https://accounts.google.com/o/oauth2/v2/auth. This endpoint handles active session lookup, authenticates the user, and obtains user consent. The endpoint is only accessible over SSL, and information technology refuses HTTP (not-SSL) connections.

The authorization server supports the following query cord parameters for installed applications:

Parameters
client_id	Required The client ID for your application. You can find this value in the API Console Credentials page.
redirect_uri	Required Determines how Google'due south authorization server sends a response to your app. There are several redirect options available to installed apps, and you will have set your authorization credentials with a particular redirect method in mind. The value must exactly friction match one of the authorized redirect redirect URIs for the OAuth two.0 customer, which yous configured in your client'south API Console Credentials page. If this value doesn't match an authorized URI, you will get a redirect_uri_mismatch error. The table beneath shows the appropriate redirect_uri parameter value for each method: redirect_uri values Custom URI scheme com.example.app:redirect_uri_path or com.googleusercontent.apps.123:redirect_uri_path com.example.app is the opposite DNS notation of a domain under your control. The custom scheme must contain a menstruum to exist valid. com.googleusercontent.apps.123 is the reverse DNS annotation of the client ID. redirect_uri_path is an optional path component, such as /oauth2redirect. Note that the path should begin with a single slash, which is different from regular HTTP URLs. Loopback IP address http://127.0.0.i:port or http://[::1]:port Query your platform for the relevant loopback IP address and start an HTTP listener on a random available port. Substitute port with the actual port number your app listens on. Manual copy/paste urn:ietf:wg:oauth:ii.0:oob Programmatic extraction urn:ietf:wg:oauth:2.0:oob:auto
response_type	Required Determines whether the Google OAuth two.0 endpoint returns an authorization code. Set the parameter value to code for installed applications.
telescopic	Required A space-delimited list of scopes that identify the resource that your application could access on the user's behalf. These values inform the consent screen that Google displays to the user. Scopes enable your awarding to only request access to the resources that it needs while besides enabling users to command the amount of access that they grant to your awarding. Thus, there is an inverse human relationship betwixt the number of scopes requested and the likelihood of obtaining user consent.
code_challenge	Recommended Specifies an encoded code_verifier that will be used equally a server-side claiming during authorisation code exchange. See create lawmaking challenge department to a higher place for more data.
code_challenge_method	Recommended Specifies what method was used to encode a code_verifier that will exist used during authority code substitution. This parameter must exist used with the code_challenge parameter described above. The value of the code_challenge_method defaults to patently if not nowadays in the request that includes a code_challenge. The only supported values for this parameter are S256 or obviously.
state	Recommended Specifies any string value that your application uses to maintain state betwixt your authorisation request and the authority server'southward response. The server returns the exact value that you lot send as a proper name=value pair in the URL fragment identifier (#) of the redirect_uri after the user consents to or denies your application's admission request. You tin use this parameter for several purposes, such as directing the user to the correct resource in your application, sending nonces, and mitigating cantankerous-site request forgery. Since your redirect_uri can be guessed, using a country value tin increment your assurance that an incoming connection is the result of an hallmark asking. If yous generate a random string or encode the hash of a cookie or another value that captures the client'south state, you can validate the response to additionally ensure that the asking and response originated in the same browser, providing protection against attacks such as cross-site asking forgery. See the OpenID Connect documentation for an instance of how to create and confirm a state token.
login_hint	Optional If your awarding knows which user is trying to cosign, it tin use this parameter to provide a hint to the Google Hallmark Server. The server uses the hint to simplify the login menstruum either past prefilling the email field in the sign-in form or past selecting the appropriate multi-login session. Set up the parameter value to an email accost or sub identifier, which is equivalent to the user'south Google ID.

The tabs beneath show sample authorization URLs for the different redirect URI options.

The URLs are identical except for the value of the redirect_uri parameter. The URLs too contain the required response_type and client_id parameters as well as the optional country parameter. Each URL contains line breaks and spaces for readability.

Custom URI scheme

https://accounts.google.com/o/oauth2/v2/auth?  telescopic=e-mail%20profile&  response_type=code&  country=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&  redirect_uri=com.example.app%3A/oauth2redirect&  client_id=client_id            

Loopback IP address

https://accounts.google.com/o/oauth2/v2/auth?  scope=email%20profile&  response_type=code&  country=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&  redirect_uri=http%3A//127.0.0.1%3A9004&  client_id=client_id            

Copy/Paste

https://accounts.google.com/o/oauth2/v2/auth?  telescopic=e-mail%20profile&  response_type=code&  state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.instance.com%2Ftoken&  redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&  client_id=client_id            

https://accounts.google.com/o/oauth2/v2/auth?  scope=electronic mail%20profile&  response_type=code&  state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&  redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&  client_id=client_id            

Step iii: Google prompts user for consent

In this step, the user decides whether to grant your application the requested admission. At this phase, Google displays a consent window that shows the name of your application and the Google API services that it is requesting permission to access with the user'due south authorization credentials and a summary of the scopes of access to be granted. The user can and so consent to grant access to one or more scopes requested by your application or refuse the request.

Your application doesn't demand to exercise anything at this stage every bit information technology waits for the response from Google'southward OAuth two.0 server indicating whether whatsoever access was granted. That response is explained in the post-obit step.

Errors

Requests to Google'south OAuth 2.0 say-so endpoint may brandish user-facing mistake messages instead of the expected authentication and authorization flows. Mutual fault codes and suggested resolutions are listed below.

admin_policy_enforced

The Google Business relationship is unable to authorize i or more scopes requested due to the policies of their Google Workspace administrator. Come across the Google Workspace Admin help commodity Command which tertiary-political party & internal apps admission Google Workspace information for more information about how an administrator may restrict admission to all scopes or sensitive and restricted scopes until access is explicitly granted to your OAuth client ID.

disallowed_useragent

The authorization endpoint is displayed inside an embedded user-amanuensis disallowed by Google'southward OAuth 2.0 Policies.

Android

Android developers may encounter this mistake message when opening authorization requests in android.webkit.WebView. Developers should instead use Android libraries such every bit Google Sign-In for Android or OpenID Foundation's AppAuth for Android.

Web developers may encounter this error when an Android app opens a general web link in an embedded user-amanuensis and a user navigates to Google's OAuth 2.0 authorization endpoint from your site. Developers should allow general links to open in the default link handler of the operating organization, which includes both Android App Links handlers or the default browser app. The Android Custom Tabs library is too a supported option.

iOS

iOS and macOS developers may encounter this fault when opening say-so requests in WKWebView. Developers should instead utilise iOS libraries such as Google Sign-In for iOS or OpenID Foundation'south AppAuth for iOS.

Web developers may encounter this error when an iOS or macOS app opens a general web link in an embedded user-agent and a user navigates to Google'south OAuth 2.0 authorization endpoint from your site. Developers should allow general links to open in the default link handler of the operating system, which includes both Universal Links handlers or the default browser app. The SFSafariViewController library is too a supported option.

org_internal

The OAuth client ID in the asking is function of a project limiting access to Google Accounts in a specific Google Deject Organization. For more data about this configuration option see the User type section in the Setting up your OAuth consent screen help article.

redirect_uri_mismatch

The redirect_uri passed in the authorization request does not lucifer an authorized redirect URI for the OAuth client ID. Review authorized redirect URIs in the Google API Console Credentials folio.

The passed redirect_uri may be invalid for the client type.

Step 4: Handle the OAuth 2.0 server response

The manner in which your awarding receives the potency response depends on the redirect URI scheme that it uses. Regardless of the scheme, the response will either contain an potency code (lawmaking) or an fault (error). For example, error=access_denied indicates that the user declined the request.

If the user grants access to your application, you lot can exchange the potency code for an access token and a refresh token as described in the next step.

Footstep 5: Exchange authorization code for refresh and admission tokens

To commutation an authorization lawmaking for an admission token, call the https://oauth2.googleapis.com/token endpoint and set the following parameters:

Fields
client_id	The customer ID obtained from the API Console Credentials folio.
client_secret	The client secret obtained from the API Panel Credentials page.
code	The authority lawmaking returned from the initial asking.
code_verifier	The code verifier you lot created in Step 1.
grant_type	As defined in the OAuth 2.0 specification, this field'south value must exist set to authorization_code.
redirect_uri	Ane of the redirect URIs listed for your project in the API Panel Credentials page for the given client_id.

The following snippet shows a sample request:

POST /token HTTP/one.1 Host: oauth2.googleapis.com Content-Type: application/10-www-form-urlencoded  code=iv/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto& grant_type=authorization_code

Google responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

Fields
access_token	The token that your application sends to authorize a Google API request.
expires_in	The remaining lifetime of the admission token in seconds.
id_token	Note: This property is but returned if your request included an identity scope, such every bit openid, profile, or email. The value is a JSON Web Token (JWT) that contains digitally signed identity data well-nigh the user.
refresh_token	A token that you can utilize to obtain a new access token. Refresh tokens are valid until the user revokes access. Note that refresh tokens are e'er returned for installed applications.
telescopic	The scopes of access granted by the access_token expressed as a listing of space-delimited, example-sensitive strings.
token_type	The blazon of token returned. At this time, this field's value is always set up to Bearer.

The post-obit snippet shows a sample response:

{   "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",   "expires_in": 3920,   "token_type": "Bearer",   "telescopic": "https://www.googleapis.com/auth/drive.metadata.readonly",   "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }

Calling Google APIs

After your application obtains an access token, you can use the token to brand calls to a Google API on behalf of a given user business relationship if the telescopic(s) of access required past the API have been granted. To practice this, include the access token in a asking to the API by including either an access_token query parameter or an Authorisation HTTP header Bearer value. When possible, the HTTP header is preferable, because query strings tend to exist visible in server logs. In almost cases you can use a client library to set up your calls to Google APIs (for case, when calling the Bulldoze Files API).

You tin can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground.

HTTP Get examples

A call to the bulldoze.files endpoint (the Bulldoze Files API) using the Authority: Bearer HTTP header might wait like the following. Note that you demand to specify your own access token:

Go /drive/v2/files HTTP/one.one Host: www.googleapis.com          Say-so: Bearer            access_token                  

Here is a call to the same API for the authenticated user using the access_token query cord parameter:

GET https://www.googleapis.com/bulldoze/v2/files?access_token=access_token        

curl examples

You can test these commands with the gyre control-line application. Here'due south an instance that uses the HTTP header option (preferred):

curl -H "Dominance: Bearer          access_token" https://www.googleapis.com/drive/v2/files

Or, alternatively, the query string parameter selection:

curl https://world wide web.googleapis.com/bulldoze/v2/files?access_token=access_token        

Refreshing an access token

Admission tokens periodically expire and go invalid credentials for a related API request. You can refresh an admission token without prompting the user for permission (including when the user is non present) if yous requested offline access to the scopes associated with the token.

To refresh an admission token, your awarding sends an HTTPS Post asking to Google'due south authorization server (https://oauth2.googleapis.com/token) that includes the post-obit parameters:

Fields
client_id	The client ID obtained from the API Console.
client_secret	The client secret obtained from the API Console. (The client_secret is not applicable to requests from clients registered equally Android, iOS, or Chrome applications.)
grant_type	Every bit defined in the OAuth 2.0 specification, this field's value must exist set to refresh_token.
refresh_token	The refresh token returned from the authorization code exchange.

The following snippet shows a sample asking:

Post /token HTTP/one.one Host: oauth2.googleapis.com Content-Type: application/x-www-course-urlencoded  client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token

As long every bit the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

{   "access_token": "one/fFAGRNJru1FTz70BzhT3Zg",   "expires_in": 3920,   "telescopic": "https://world wide web.googleapis.com/auth/drive.metadata.readonly",   "token_type": "Bearer" }

Notation that at that place are limits on the number of refresh tokens that volition be issued; one limit per client/user combination, and another per user across all clients. Y'all should save refresh tokens in long-term storage and continue to utilise them as long as they remain valid. If your application requests too many refresh tokens, information technology may run into these limits, in which case older refresh tokens will finish working.

Revoking a token

In some cases a user may wish to revoke admission given to an application. A user can revoke access by visiting Account Settings. See the Remove site or app access section of the Third-political party sites & apps with access to your account support document for more information.

It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is of import in instances where a user unsubscribes, removes an application, or the API resource required by an app have significantly inverse. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.

To programmatically revoke a token, your application makes a asking to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

curl -d -X -Mail --header "Content-blazon:awarding/x-www-form-urlencoded" \         https://oauth2.googleapis.com/revoke?token={token}        

The token tin can be an admission token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token volition likewise exist revoked.

If the revocation is successfully processed, then the HTTP status lawmaking of the response is 200. For error conditions, an HTTP status code 400 is returned along with an error code.

Farther Reading

The IETF All-time Current Practice OAuth 2.0 for Native Apps establishes many of the best practices documented here.

fordmorive.blogspot.com

Source: https://developers.google.com/identity/protocols/oauth2/native-app

Share this post