Yahoo’s OAuth 2.0 APIs can be used for both authentication and authorization. In this document, we will focus on our OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification.
The naming and syntax convention for terminology used in this documentation is based on the OpenID Connect Core specification.
OpenID Connect is a public-key-encryption-based authentication framework that offers the following:
- globally increased Internet security by having the most expert service providers be responsible for verifying user identity.
- an easy, reliable, and secure method for developers to authenticate users across websites and applications while eliminating the need to store and manage user passwords.
- an easier way for users to sign up and register, which can reduce the abandonment rate of your website or application.
Before starting, take a few minutes to digest the key concepts listed below. For a comprehensive list of terminology, see OpenID Connect Core 1.0 Terminology.
Access Tokens are credentials for accessing protected resources. The Access Token is issued to you (the Client) after the Resource Owner (i.e., user) has authorized your site or application to access his or her protected data.
Authentication is the process of verifying the identity of a user signing in to a site or an application. In OpenID Connect, the authentication is decentralized, so the user’s information is not mapped to a private database. Thus, Yahoo as the Identity Provider allows Relying Parties or Clients to use OpenID Connect to authenticate their users through our service. As a result, users can use the same Yahoo credentials on multiple websites that support the OpenID Connect specification.
The ID Token is the primary extension that OpenID Connect makes to OAuth 2.0 to authenticate users. The ID Token is a security token containing Claims (information) about the authentication of a user performed by Yahoo, and potentially other Claims requested by you. The ID Token is represented as a JSON Web Token (JWT).
Identity Provider (IDP)¶
The IDP is a party that offers user authentication as a service. In this document, Yahoo is the IDP. For more information, see “What do ‘IDP’ and ‘RP’ stand for?” and “Who can be an IDP?” in the OpenID Connect FAQ and Q&As.
JSON Web Token (JWT)¶
JWT is a compact, URL-safe means of representing and transferring claims between two parties.
Refresh Tokens are credentials used to obtain Access Tokens when Access Tokens become invalid or expire. You receive an Access Token, a Refresh Token, and optionally, an ID Token from Yahoo in the Authorization Code Flow or in the Hybrid Flow.
Relying Party (RP) / Client¶
The RP or Client is an application that outsources its user authentication function to an IDP. For example, you, as a developer, might want to use Yahoo as the IDP to authenticate the users of your site or application: this would make you the RP.
The Resource Owner is an entity (person or thing) capable of granting access to a protected resource. A Resource Owner that is a person is referred to as an End-User. We’ll be referring to End-Users simply as users in the document because this document is intended for developers.
Single-Sign On (SSO)¶
SSO allows users to sign in once and access multiple related sites/applications. OpenID Connect makes SSO possible. In this document, users sign in at Yahoo for SSO.
You present an authorization code or Refresh Token to the token endpoint to obtain an Access Token and/or ID Token. The token endpoint is used in every flow except for the Implicit Grant Flow (where the Access Token or ID Token can be issued directly). See Token Endpoint in RFC 6749 for more information.
Yahoo’s token endpoint is
Supported Authentication Flows¶
We support the following three OpenID Connect flows:
When using the Implicit Flow, the Access Token and ID Token are returned from the Authorization Endpoint: the Token Endpoint is not used. The Implicit Flow is mainly used by applications implemented in a browser using a scripting language. The Access Token and ID Token are returned directly to the application, which may expose them to the user and applications that have access to the User Agent. The Authorization Server (Yahoo) does not perform Client Authentication. The flow steps are enumerated and described in the OpenID Connect Core specification’s Implicit Flow Steps.
The Implicit Flow in OpenID Connect is the same as the Implicit Grant Flow in OAuth 2.0.
When to Use¶
In the Implicit Flow, you get the ID Token and an optional Access Token directly from authorization endpoint. This is useful if your application only needs to authenticate the user and gain short-term access to the user’s private data. Note that this flow does not support the issuance of Refresh Tokens, so you won’t have long-term access to the user’s private data.
When using the Hybrid Flow, some tokens are returned from the Authorization Endpoint and others are returned from the Token Endpoint. See the Hybrid Flow Steps in the Open Connect Core 1.0 specification.
When to Use¶
The Hybrid Flow is a combination of the above two flows. It allows you (the Client) to request either the ID Token or Access Token or both, along with the authorization code from the authorization endpoint. The code, thus obtained, can then be exchanged for the remaining tokens from the token endpoint.
For example, suppose you are primarily interested in using SSO. You can first obtain the code and the ID Token from the authorization endpoint. While the ID Token is being decoded to sign in the user, you can simultaneously exchange the code for the Access Token and Refresh Token from the token endpoint in a non-blocking manner.
Although the Hybrid Flow offers more flexibility with the ability to request and use tokens, it is less secure than the Authorization Code Flow because the tokens are exposed to the User Agent.