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.
Supported Authentication Flows¶
We support the following two OpenID Connect flows:
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 supports the application receiving some tokens in the URL response as well as the ‘code’ as defined in the Authorization Code Grant flow. 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.