What is OpenID Connect?

Scott Brady
Scott Brady
・ OpenID Connect ・ Updated March 2021
OpenID Connect logo

OpenID Connect (OIDC) provides a simple identity layer on top of the OAuth 2.0 protocol, enabling Single Sign-On (SSO) and API access in one round trip. It brings the missing user authentication story and identity layer to OAuth.

In this article, you’ll see how OpenID Connect differs from OAuth, and key OpenID Connect features such as identity tokens and the user info endpoint.

OAuth vs. OpenID Connect

Much to everyone’s disappointment, OAuth 2 is not an authentication protocol. Instead, it is an authorization protocol, allowing an application to ask a user if it can access an API on their behalf. It is a delegation protocol.

Over the years, many people have tried to bend the protocol to their will and turn OAuth into something that it is not. This is one reason why, historically, there are so many different “flavors” of OAuth.

Unsurprisingly, extending OAuth is quite hard to do on your own, and many, including the likes of Apple and Facebook, have learned this the hard way.

OpenID Connect: OAuth + Identity

OpenID Connect 1.0 (OIDC) is a standard from the OpenID Foundation that extends the OAuth protocol with a simple identity layer. This layer builds on top of OAuth, rather than modifying it, and allows both protocols to work together, providing both Single Sign-On (SSO) and authorization to access APIs on the user’s behalf.

OpenID Connect achieves this using identity tokens, and a new API called the user info endpoint. It turns your OAuth authorization server into an identity provider (or OpenID provider).

Identity Tokens and OIDC Authentication

An identity token describes the authentication event that took place at the identity provider. It contains information such as when the user last authenticated and how they authenticated. An identity token is always a signed JSON Web Token (JWT).

Unlike an OAuth access token, the identity token is meant to be read and validated by the application that made the authorization request. If the token is valid (issued by the correct identity provider, intended for this application, and signed using the expected key), then the application will read the authentication data. If the authentication data meets the application’s policy, then it can start its own session for the authenticated user.

For example, your admin portal may check that the user authenticated in the past hour, used Multi-Factor Authentication (MFA), and used their corporate Active Directory account rather than social authentication. If these requirements are not met, then the application can decline to create a session and send the user back to the identity provider to re-authenticate.

Check out my article understanding identity token for a deep dive into identity tokens.

Example Identity Token Payload

A decoded identity token typically contains the following information: 

{
  "nbf": 1615114977, // not before
  "exp": 1615115277, // expiry
  "iat": 1615114977, // issued at
  "iss": "https://idp.local", // who issued the token (the identity provider) 
  "aud": "my_client_app", // the expected audience of the token (the client application)
  "nonce": "PdxaXTg_THsyna9wfYpsD-_qVpWjlyjjcl864K0wbxY", // no more than once (a random value, linking the authorization request to the identity token)
  "s_hash": "2KxmL27CM9VC5eL6WkS1uw", // a hash of the state parameter used in the initial authorization request (detects injection)
  "sid": "de71c582d82d286b5c6007d33da8184b", // the session ID
  "sub": "5be86359073c434bad2da3932222dabe", // the subject ID (the unique ID for the user)
  "auth_time": 1615114970, // when the user last authenticated
  "idp": "local", // who the user authenticated with (e.g. "Google")
  "amr": [ // authentication method reference - how the user authenticated
    "pwd" // (they used a password)
  ]
}

UserInfo Endpoint

The user info endpoint is a new API exposed by the identity provider. It allows applications to use an access token to discover identity data about the user.

The user info endpoint has its own set of scopes that authorize application’s to receive specific claim types about the user. For example, if the application is authorized to use the profile scope, then it can receive the user’s name, date of birth, and username from the user info endpoint.

If the application does not ask for an access token, identity claims will instead be embedded in the identity token. I recommend using the user info endpoint rather than embedding large amounts of PII in an identity token.

Example UserInfo Response

The user info endpoint returns the user’s claims in a JSON payload: 

{
    "sub": "5be86359073c434bad2da3932222dabe",
    "preferred_username": "scottbrady91",
    "name": "Scott Brady",
    "given_name": "Scott",
    "picture": "https://www.scottbrady91.com/img/scott_brady1901.jpeg"
}

Standard Identity Scopes

OpenID Connect defines a standard set of identity scopes that can be used against the user info endpoint. The most common are:

Scope Claim types
openid sub
profile name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at
email email and email_verified
phone phone_number and phone_number_verified

Single Logout, Sessions, and Flows

Now that your OAuth authorization server now has the concept of a session and SSO, it can also handle Single LogOut (SLO) and session management. This is a whole other topic, though, so I’m going to point you in the direction of the OIDC specifications.

For further reading, check out the endpoints available with OpenID Connect or the grant types it supports. Or, if you’re keen to build your own OpenID Connect identity provider, check out the open-source OpenID Connect framework: IdentityServer.

OpenID vs. OpenID Connect

OpenID 1.0 and 2.0 are obsolete specifications that pre-date OpenID Connect by almost 10 years. OpenID was a separate, custom authentication protocol, not related to OAuth or OpenID Connect.

OpenID didn’t see much adoption; however, OpenID Connect is has seen significant success working alongside OAuth, replacing older protocols such as WS-Federation and SAML as the go-to for SSO.

There’s a lot of confusion around OpenID vs. OpenID Connect, which always seems to boil down to the following questions:

Is OpenID Dead?

Yes, OpenID is an obsolete standard that is no longer supported by the OpenID Foundation. Use OpenID Connect instead.

Is OpenID Connect Dead?

No, you’re thinking of OpenID. OpenID Connect is very much alive.

Learn OAuth and OpenID Connect

I think it is crucial that you understand the protocols you are using and what you should use them for. To learn more about OAuth and OpenID Connect, I recommend the following resources: