This chapter provides step-by-step instructions for using Yahoo’s OpenID Connect and is divided into the following three sections:
I. Setting Up: Create an Application and Get OAuth 2.0 Credentials¶
After you have a Yahoo account, create an application to get your Client ID (Consumer Key) and Client Secret (Consumer Secret) for later use in the OpenID Connect / OAuth 2.0 flows.
In the Create Application form, provide an application name and a callback domain. The callback domain is where Yahoo will send responses to your authentication request, so you’ll want to be the domain owner.
If your application needs to access private user data from Yahoo APIs, you’ll need to request permissions to Yahoo APIs in the checklist under API Permissions. For the purpose of demonstration in this getting started, check Mail and then select Read.
Finish creating your application by clicking Create App.
You can always go to My Apps to view your applications and OAuth credentials.
II. Implicit Flow: Authenticating Users¶
This is the most direct and simplest flow. It is also useful for authenticating users with single sign-on (SSO) and optionally retrieving some user data during the SSO process. In the Implicit Flow, all tokens, including the ID Token, are returned directly from the authorization endpoint as part of the URI fragment. The token endpoint is not used at all.
The diagram below outlines the basic steps of the Implicit Flow and the parties involved (Application/Yahoo/User). See the steps in the sections below for details.
Step 1: Send an authentication request to Yahoo¶
After you created your application, you were given
a Client ID (Consumer Key) and a Client Secret (Consumer Secret). You’ll be using
the Client ID as the
client_id and the callback domain you provided before
redirect_uri to receive the response from Yahoo after the user authorizes
To create an authentication request, you’ll need Yahoo’s OAuth 2.0 authorization endpoint, a supported HTTP method, and the request parameters given below. To receive an ID Token, be sure to use one of the following:
OAuth 2.0 Authorization Endpoint:
Supported HTTP Methods:
The request parameters below can either be transmitted in the request body using
POST or as part of the query string with
||(Required) The Client ID (Consumer Key) provided to you when you created your application.|
||(Required) Yahoo redirects users to this URL after they agree
to use SSO and authorize access to their private data.
Provide the complete URL including the HTTP/HTTPS protocol. If the user should not
be redirected to your server, you should specify the callback as
||(Required) For the Implicit Flow, you must use either
(Required for OpenID Connect) To get an ID Token to authenticate a user,
you are required to specify the scope identifier
Additionally, to access private user data from the Yahoo APIs, include the relevant API scope identifiers. The scopes can be delimited by a space or comma. In the example below, the scope identifier is specified for requesting the ID Token and an Access Token that provides read access to the Yahoo Mail API:
||(Recommended) Create a unique session token to maintain state between the request and the callback. By cryptographically binding the value of this parameter to a browser cookie, you can mitigate cross-site request forgery (CSRF, XSRF).|
||(Optional) Language identifier. The default value is
||(Required) An arbitrary URL-safe string used to associate your client session with an ID Token and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. See Nonce Notes for more information.|
(Optional) A string value specifying whether Yahoo prompts the user for
reauthentication or consent. To prompt the user to re-authorize your application,
This parameter can be used to make sure that the user is still present for the current session or to bring attention to the request.
||(Optional) You can specify the allowable elapsed time in seconds since the last time the user was actively authenticated by Yahoo. If the elapsed time is greater than this value, Yahoo will attempt to re-authenticate the user.|
Step 2: Obtain user consent¶
When a user attempts to sign in to your application and you send Yahoo an authentication request for SSO, Yahoo will first authenticate the user and then present the user with the Yahoo Consent Screen shown below.
From the Yahoo Consent Screen, users can either agree or disagree to grant the permissions you are requesting.
No developer action is required in this step.
Now that you have formed your OpenID Connect authentication request, copy and paste it into your Web browser’s address bar. You’ll be redirected to the same consent screen. Click Agree to go to your redirect URL to see an encoded ID Token similar to the one below:
Step 3: Decode the ID Token¶
After agreeing to SSO, the user is redirected back
to the URL specified by
redirect_uri. The ID Token is appended to the
in the URI fragment as shown below.
The ID Token is a security token containing authentication information called Claims. If you request API scopes when creating an application on YDN and includes the scope in the authentication request, the returned ID Token may also contain some additional information.
See Decoding the ID Token to learn more about the ID Token, how to decode and validate it, and the additional information that may be returned in the claims.