Write an OpenID Connect server in three simple steps

Date: : Last modified:2014/07/25 OAuth, OpenID Connect

An OpenID Connect server is just an OAuth 2.0 server on steroids. What it does it to return the ID Token, which contains information about the authentication event for the user at the door, in addition to the Access Token. This article explains how to write a simple OpenID Connect server using an OAuth 2.0 server as the basis.

1. Add OpenID Connect request / response handling to Authorization Endpoint

Assuming you have OAuth 2.0 server code, what you need to add on top of it is code to handle a few extra parameters used for user authentication.

When a client wants to authenticate the user, it will pass the following information (the green ones are required for OAuth and the red portion is specific to OpenID Connect):

  • client_id: the client id of the application;
  • redirect_uri: https endpoint to which the user should be returned;
  • scope: openid;
    • The scope can also have email, profile, address, phone, offline_access values.

  • response_type: one of “id_token“, “token id_token“, “code“;

The client may also pass these.

  • prompt: Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. Defined values are none, login, consent, select_account.
  • max_age: Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated.

On the server side, you have to do the following upon receipt. In addition to the normal OAuth processing:

  • Check if scope includes openid. If it does not, just proceed with normal OAuth processing; 
  • Find out what response_type the request was using;
  • Create the id_token as follows:
    • Make the JSON with following parameters:
      • iss: https URI that indicates the issuer;
      • sub: identifier of the user at the issuer;
      • aud: client_id of the requesting client;
      • nonce: the nonce parameter value received from the client;
      • exp: expiration time of this token;
      • iat: time when this token was issued;
      • auth_time: time the authentication happened;
      • at_hash: the first half of a hash of the access token;
    • Example: 
         "iss": "https://server.example.com",
         "sub": "alice",
         "aud": "clinet-id-received",
         "nonce": "n-0S6_WzA2Mj",
         "exp": 1311281970,
         "iat": 1311280970,
         "auth_time": 1311280969,
         "at_hash": "MTIzNDU2Nzg5MDEyMzQ1Ng"
    • Sign it with JSON Web Signature (JWS) using your RSA private key. You should use a library for JWS. The result is the ID Token to be returned.
  • If the response type is ‘code‘:
    • Save the id_token and send the code back as usual in OAuth.
  • Else if the response type is ‘id_token‘:
    • Send the id_token back to the redirect_uri in the fragment.
  • Else if the response type is ‘token id_token‘:
    • Send the Access Token and ID Token back to the redirect_uri in the fragment.
  • If an error occurs: You have already implemented OAuth error responses, have not you?

Unless the response type was ‘code’, you are basically done here.

2. Make Token Endpoint capable of returning ID Token

To handle a request with the response_type ‘code’, you need to add functionality to the Token Endpoint, which returns the previously created ID Token.

  • When you received the ‘code’, check if it is associated with a previously created ID Token. It could be that ‘code’ has a special strtucture that indicates it or you might pull it from the database you created. 
  • Pull the associated ID Token out from wherever you have stored it and return it in the JSON response with the name “id_token”, e.g.:
       "access_token": "SlAV32hkKG",
       "token_type": "Bearer",
       "refresh_token": "8xLOxBtZp8",
       "expires_in": 3600,
       "id_token": "previously.created.id_token"

    The only addition to the normal OAuth 2.0 is this single parameter, id_token.

  • refresh_token should be returned if the scope included offline_access.
  • If an error occurs: this is just yet another OAuth 2.0 error response that you have already implemented.

3. (Optional) A protected resource: UserInfo Endpoint

You can actually return all the requested claims in the ID Token, but since you might want it to be small for one reason or another, you might want to return most of them from a protected resource. We have standardized resource as the UserInfo Endpoint. It is an OAuth 2.0 protected resource. Most servers will probably implement this but it is not strictly required.

The client accesses the UserInfo endpoint using the Access Token returned to it.  What server needs to do is:

  • Verify that the Access Token is valid; 
  • Pull the claims about the user associated with the Access Token out of its database;
    • The claim set will be one of email, profile, address, phone or a combination of them. The scope elements above map to the following sets of claims:
    • emailemail and email_verified;
    • profilename, family_name, given_name, middle_name, nickname, preferred_usernameprofile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
    • address: address, which is a structure with the following members:
      • formatted, street_address, locality, region, postal_code, country;
    • phonephone_number and phone_number_verified;
  • Return them as JSON, e.g.:
       "sub": "alice",
       "name": "Alice de Wonderland",
       "given_name": "Alice",
       "family_name": "de Wonderland",
       "email": "alice@example.com",
       "picture": "http://example.com/alice/me.jpg"
  • If an error occurs, just return the OAuth 2.0 error.

That’s it.

There are additional features in OpenID Connect, but these are the minimal things that you need to implement as a server.

Why is there an ID Token?

As you can see, it is nearly as simple as it could be. One alternative design would be to get rid of the ID Token and create another endpoint.

We actually have started off there. We had a check_id endpoint at the beginning that returned the content of what we have as ID Token now. We moved to ID Token model later for the following reasons:

  • Some social network clients could not tolerate the user experience degradation caused by the round trip time required to use the check_id endpoint; 
  • Some clients needed a token that can be used to create a session. The ID Token serves this purpose.
  • Some clients needed to have an integrity check on access_token; we could implement it using the ID Token.

Also, we could have the returned id_token as the access token, many implementers opposed that; they wanted to keep doing what they were already doing with their access tokens.

Thus, the ID Token was the most straightforward solution. Indeed, we have made it as simple as possible, but no simpler. 😉

Ads by Google


OpenID Connect Provider Testing

OpenID Connect Test Facility Preview Available

Andreas Åkre Solberg and Roland Hedberg from Fedla

Read more

no image

OpenID Summit in Den Hague, Netherlands (Nov. 21)

The OpenID Foundation is hosting an OpenID worksho

Read more


Review Comments for draft-ietf-oauth-proof-of-possession-02

Proof-Of-Possession Semantics for JSON Web Tokens

Read more

The identity layer

OpenID Connect is here! – An Identity Layer on the internet

Celebrate! OpenID Connect 1.0 Final is here! Aft

Read more

no image

[OAuth] Resource Owner != Client User

I have been preaching this numerous time, but let

Read more

no image

Approve OpenID Connect Implementer’s Drafts!

Hi. OpenID Conenct Implementer's Draft voting h

Read more


Identity, Authentication + OAuth = OpenID Connect

Read more


draft 02 of OpenID 2.0 to Connect Migration is now available

OpenID 2.0 to OpenID Connect Migration (aka OID2 t

Read more

OpenID Connect on OAuth Logo

OpenID Connect Stripped down to just “Authentication” (aka OAuth Authentication)

So, OpenID Connect provides a lot of advanced faci

Read more

OpenID Connect on OAuth Logo

Refactoring OpenID Connect Drafts

After the Berlin OpenID AB/C WG F2F meeting, I hav

Read more

Ads by Google

  • Helios VIcente

    I have registrered in order to get a password but after 1 day, I don’t have any password to read the post . Should I ask for a password in any other place ? Thanks

    • http://www.sakimura.org Nat Sakimura

      Sorry, this article is still in the draft status. When I publish it, you will be able to see it.

  • Pingback: Mike Jones: self-issued » OpenID Connect Server in a Nutshell()

  • Pingback: OpenID Connect Server in a Nutshell | OpenID()

  • Mike Schwartz

    This is awesome…. but if you want a slightly more comprehensive OpenID Connect server that also supports the UMA profile of OAuth, you may want to look at ox. See http://gluu.org for more info.

  • tomvo

    Nice article. I was wondering on what grant type the authorization requests are based. Would that be Resource Owner Password Credentials or Client Credentials?

    • http://www.sakimura.org Nat Sakimura

      The above article is based on the code grant type. We have also defined a profile for implicit grant type as well.

  • Pingback: OpenID Connect Server in a Nutshell | Open Identity Exchange()

  • Pingback: Open ID Connect Provider - Persist ID Tokens? - DexPage()

    • Nat

      You need to save what is to be in ID Token somewhere until you send the ID Token out.
      Somewhere can be on the server where “code” is being managed, or inside the “code” itself, in which case the server can be more-or-less stateless.
      Once the server send the ID Token out, it does not need to save it anywhere.

Ads by Google

Screen Shot 2015-06-18 at 23.47.23
On the XARA vulnerability on MacOS X and iOS

Just came across this article: Appl

no image
Apple’s answer to the in-secure use of in-app browser? — iOS 9 introduces SFSafariViewController

Apple forcing developpers to use in

JWS, JWT, and others now RFC!

It has taken soooo long , but JSON

Review Comments for draft-ietf-oauth-proof-of-possession-02

Proof-Of-Possession Semantics for J

Merry Christmas 2014
Seasons Greetings 2014

Seasons greetings video as a replac