Understanding OpenID Authentication through Examples

In the article "Understanding OAuth2 through Examples[1]", we explained the working principle of the OAuth2 Authorization Code mode by example. In the example, after the user (tonybai) authorized the photo printing service, it used the code provided by the user (actually assigned by the authorization server and redirected to the photo printing service through the user's browser) to exchange for an access token from the authorization server, and finally used the access token to read the user's photo information from the cloud disk system.

However, the photo printing service that has received the access token does not know which user on the cloud disk service the access token represents. If the cloud disk service does not return the user name (tonybai) in the photo list interface, the photo printing service needs to create a temporary user ID for the user who authorized it. When the tonybai user visits the photo printing service again a week later, the photo printing service needs to go through the OAuth2 authorization process again, which is not a good user experience.

From the perspective of the photo printing service, it hopes to obtain the user's identity information when the user uses the service for the first time and authorizes it, add the user to its own user system, and automatically identify and authenticate the user's identity when the user subsequently uses the service through a similar session-based authentication mechanism[2]. This can avoid the user's unpleasant experience of registering an additional account separately, and avoid the tedious authorization process when the user uses the service next time.

However, although OAuth 2.0 is a security protocol that requires user interaction, it is not an identity authentication protocol. However, many applications such as photo printing services still have a strong demand for user identity authentication through large-scale applications such as cloud disk systems, so many manufacturers have developed their own dedicated standards, such as Facebook, Twitter, LinkedIn and GitHub, etc., but these are dedicated protocols and lack standardization. Developers have to develop and adapt them one by one.

Therefore, the OpenID Foundation[3] developed an open identity authentication protocol standard called OpenID Connect (OIDC for short)[4] based on OAuth2.0, which can be used by different manufacturers.

In this article, we will introduce the identity authentication principle based on OpenID. With the previous article OAuth2 as a foundation, OIDC is very easy to understand.

1. Introduction to OpenID Connect (OIDC)

OpenID Connect is an open standard released by the OpenID Foundation in February 2014. It defines an interoperable way to perform user authentication using OAuth 2.0. Because the protocol is designed to be interoperable, an OpenID client application can interact with different identity providers using the same set of protocol languages, without having to implement a slightly different set of protocols for each identity provider. OpenID Connect is built directly on top of OAuth 2.0 and maintains compatibility with OAuth2.0. In the real world, in most cases, OIDC is deployed together with the OAuth infrastructure that protects other APIs.

When we studied OAuth 2.0[5], we first learned about the entities involved in the protocol, such as Client, Authorization Server, Resource Server, Resource owner, Protected resource, and their interaction processes. Knowing these means we have mastered the core of OAuth2. With this in mind, when we study the OIDC protocol, we also start by understanding which entities are involved in the protocol interaction and their specific interaction processes.

OpenID Connect is a protocol suite (OpenID Connect Protocol Suite[6]), which includes Core, Discovery, Dynamic Client Registration, etc.:

picture

However, here we only focus on the core 1.0 protocol specification of OpenID Connect [7].

Just as OAuth2.0 supports four authorization modes, OIDC integrates three types of identity authentication based on these four modes:

• Authentication using the Authorization Code Flow
• Authentication using the Implicit Flow
• Authentication using the Hybrid Flow

Among them, Authentication using the Authorization Code Flow, an identity authentication scheme based on the OAuth2 authorization code process, should be the most widely used. This article will also understand OIDC based on this process and give examples.

1.1 Entities and interaction flow chart in OIDC protocol

The following is a general identity authentication flow chart given in the OIDC specification. This diagram is highly abstract and suitable for the above three flows:

picture

Through this diagram, let's first recognize the three entities involved in the OIDC process:

• RP (Relying Party)

At the far left of the diagram is an entity called RP. If it corresponds to the example in the OAuth2.0 article, this RP corresponds to the photo printing service in the example, which is the Client in OAuth2.0, that is, the entity that requires user (EU) authorization.

• OP (OpenID Provider)

OP corresponds to the Authorization Server+Resource Server in OAuth2.0. The difference is that in the special scenario of OIDC, the resource stored in the Resource Server is the user's identity information.

• EU(End User)

EU, as the name implies, is the user who uses the RP service, which corresponds to the Resource Owner in OAuth2.0.

Combining these entities, the abstract flowchart above, and the interaction diagram of the OAuth2 authorization code mode, I will draw an interaction diagram between entities for OIDC identity authentication based on the authorization code mode. Here we still take the user using the photo printing service as an example:

picture

The above figure is an OIDC protocol process based on the authorization code process. It is almost exactly the same as the process of the authorization code mode in OAuth 2.0!

The only difference is that the authorization server (OP) returns an ID_TOKEN at the same time as the access_token. We call this ID_TOKEN an ID token, which is the key to OIDC identity authentication.

1.2 ID_TOKEN Composition

From the above figure, we can see that the ID_TOKEN is provided to the Client (RP) together with the ordinary OAuth access_token. Unlike the access_token, the RP needs to parse the ID_TOKEN. So what is this ID_TOKEN? In the OIDC protocol, the ID_TOKEN is a signed JWT[8].

The OIDC protocol specification specifies the field information that the jwt should contain, including required and optional fields. Here we only need to understand the following required field information:

• iss

The issuer of the token, whose value is the URL of the identity authentication service (OP), such as http://open.my-yunpan.com:8081/oauth/token, and does not contain query parameters prefixed by a question mark.

• sub

The subject identifier of the token, whose value is a unique and never reassigned identifier of the end user (EU) within the identity service (OP).

• aud

The target audience of the token, whose value is the identifier of the Client (RP), must contain the RP's OAuth 2.0 client ID (client_id), and can also contain identifiers of other audiences.

• exp

Expiration time, after which ID_TOKEN will become invalid. Its value is a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z (measured in UTC) to the expiration date/time.

• iat

The authentication time, that is, the time of the version ID_TOKEN, is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z (measured in UTC) to the authentication date/time.

Note: If the client (RP) has registered a public key with the authentication server (OP), the client public key can be used to verify the asymmetric signature of the JWT, or the client secret key can be used to symmetric sign the JWT. This method can improve the security level of the client because it can avoid transmitting the secret key on the network.

In the process of using access_token to obtain user_info in the above figure, RP can use the sub (EU unique identifier) ​​in ID_TOKEN to exchange the user's basic information at the userinfo endpoint of the authorization server. In this way, when displaying the EU logo on RP's own page, it is necessary to use a unique identifier (sub) such as 9XDF-AABB-001ACFE instead of an understandable string such as TonyBai.

Note: OpenID Connect uses a special scope value openid to control access to the UserInfo endpoint. OpenID Connect defines a set of standardized OAuth scopes that correspond to subsets of user attributes, such as profile, email, phone, address, etc.

After understanding the OIDC authentication process and the composition of ID_TOKEN, we have an intuitive understanding of OIDC. Next, we use an example to deepen our understanding of OIDC authentication.

2. OIDC Example

If you understand the examples in the article "Understanding OAuth2 by Example[9]", then it will be easy to understand the OIDC examples in this article. As mentioned earlier, OIDC is built on top of OAuth2 and is compatible with OAuth2. Therefore, the OIDC examples here are also adapted from the examples in the OAuth2 article.

Compared with the example in the OAuth2 article, the cloud disk service (my-yunpan) is removed from the OIDC example, leaving only the following structure:

 $tree -L 2 -F oidc-examples oidc-examples ├── my-photo-print/ │ ├── go.mod │ ├── go.sum │ ├── home.html │ ├── main.go │ └── profile.html └── open-my-yunpan/ ├── go.mod ├── go.sum ├── main.go └── portal.html

My-photo-print is the photo printing service and the RP entity in the oidc instance, while open-my-yunpan plays the role of cloud disk authorization service and is the OP entity in the oidc instance. Before writing and running the service, we also need to modify the /etc/hosts file of the local machine (MacOS or Linux):

 127.0.0.1 my-photo-print.com 127.0.0.1 open.my-yunpan.com

Note: Before demonstrating the following steps, please enter the two directories of oidc-examples and start each service program through go run main.go (one terminal window for each program).

2.1 User's use of my-photo-print.com photo printing service

According to the process, the user first opens the homepage of the photo printing service through a browser: http://my-photo-print.com:8080, as shown below:

picture

This is not much different from the example in the OAuth2 article. This page is also provided by the homeHandler in my-photo-print/main.go, and its home.html rendering template is basically unchanged, so I won’t go into details here.

When the user selects and clicks "Log in with a cloud disk account", the browser will open the homepage of the cloud disk authorization service (OP) (http://open.my-yunpan.com:8081/oauth/portal).

2.2 Use open.my-yunpan.com for authorization, including openid permissions

The homepage of the cloud disk authorization service is still the same, the only difference is that the requested permissions include an openid (brought over by my-photo-print's home.html):

picture

This page is also provided by the portalHandler of open.my-yunpan.com. Its logic is the same as that of the oauth2 instance, and its code is also listed here.

When the user (EU) fills in the username and password and clicks "Authorize", the browser will initiate a post request to the "/oauth/authorize" of the cloud disk authorization service to obtain the code. The authorizeHandler responsible for the "/oauth/authorize" endpoint will authenticate the user. After passing, it will assign a code and return a redirect response to the browser. The redirect address is the callback address of the photo printing service: http://my-photo-print.com:8080/cb?code=xxx&state=yyy.

2.3 Obtain access token and id_token, and use the user's unique identifier to obtain the user's basic information (profile)

This redirect is equivalent to the user's browser making a request to http://my-photo-print.com:8080/cb?code=xxx&state=yyy, providing the code to the photo printing service. The request is processed by my-photo-print's oauthCallbackHandler:

 // oidc-examples/my-photo-print/main.go // callback handler，用户(EU)拿到code后调用该handler func oauthCallbackHandler(w http.ResponseWriter, r *http.Request) { fmt.Println("oauthCallbackHandler:", *r) code := r.FormValue("code") state := r.FormValue("state") // check state mu.Lock() _, ok := stateCache[state] if !ok { mu.Unlock() fmt.Println("not found state:", state) w.WriteHeader(http.StatusBadRequest) return } delete(stateCache, state) mu.Unlock() // fetch access_token and id_token with code accessToken, idToken, err := fetchAccessTokenAndIDToken(code) if err != nil { fmt.Println("fetch access_token error:", err) return } fmt.Println("fetch access_token ok:", accessToken) // parse id_token mySigningKey := []byte("iamtonybai") claims := jwt.RegisteredClaims{} _, err = jwt.ParseWithClaims(idToken, &claims, func(token *jwt.Token) (interface{}, error) { return mySigningKey, nil }) if err != nil { fmt.Println("parse id_token error:", err) return } // use access_token and userID to get user info up, err := getUserInfo(accessToken, claims.Subject) if err != nil { fmt.Println("get user info error:", err) return } fmt.Println("get user info ok:", up) mu.Lock() userProfile[claims.Subject] = up mu.Unlock() // 设置cookie cookie := http.Cookie{ Name: "my-photo-print.com-session", Value: claims.Subject, Domain: "my-photo-print.com", Path: "/profile", } http.SetCookie(w, &cookie) w.Header().Add("Location", "/profile") w.WriteHeader(http.StatusFound) // redirect to /profile }

This handler does a lot of work. First, it uses the code to exchange access token and id_token from the authorization server. The authorization server is responsible for issuing tokens through tokenHandler:

 // oidc-examples/open-yunpan/main.go func tokenHandler(w http.ResponseWriter, r *http.Request) { fmt.Println("tokenHandler:", *r) // check client_id and client_secret user, password, ok := r.BasicAuth() if !ok { fmt.Println("no authorization header") w.WriteHeader(http.StatusNonAuthoritativeInfo) return } mu.Lock() v, ok := validClients[user] if !ok { fmt.Println("not found user:", user) mu.Unlock() w.WriteHeader(http.StatusNonAuthoritativeInfo) return } mu.Unlock() if v != password { fmt.Println("invalid password") w.WriteHeader(http.StatusNonAuthoritativeInfo) return } // check code and redirect_uri code := r.FormValue("code") redirect_uri := r.FormValue("redirect_uri") mu.Lock() ac, ok := codeCache[code] if !ok { fmt.Println("not found code:", code) mu.Unlock() w.WriteHeader(http.StatusNotFound) return } mu.Unlock() if ac.redirectURI != redirect_uri { fmt.Println("invalid redirect_uri:", redirect_uri) w.WriteHeader(http.StatusBadRequest) return } var authResponse struct { AccessToken string `json:"access_token"` IDToken string `json:"id_token,omitempty"` ExpireIn int `json:"expires_in"` } // generate access_token authResponse.AccessToken = randString(16) authResponse.ExpireIn = 3600 now := time.Now() expired := now.Add(10 * time.Minute) claims := jwt.RegisteredClaims{ Issuer: "http://open.my-yunpan.com:8091/oauth/token", Subject: ac.userID, Audience: jwt.ClaimStrings{user}, //client_id IssuedAt: &jwt.NumericDate{now}, ExpiresAt: &jwt.NumericDate{expired}, } if strings.Contains(ac.scopeTxt, "openid") { // generate id_token if contains openid mySigningKey := []byte("iamtonybai") jwtToken := jwt.NewWithClaims(jwt.SigningMethodHS256, claims) authResponse.IDToken, _ = jwtToken.SignedString(mySigningKey) } respData, _ := json.Marshal(&authResponse) w.Write(respData) }

We can see that tokenHandler first verifies the client credentials, then verifies the code. If the code passes the verification, it will assign an access_token, and decide whether to assign an id_token based on whether the scope contains openid. Here, our permission authorization includes openid, so tokenHandler generates an id_token (a jwt) and returns it to the client.

After receiving the access_token and id_token, my-photo-print's oauthCallbackHandler will parse the id_token, extract valid information such as the subject, and use the subject (the user's unique ID) in the access_token and id_token to authorize the service to obtain the user's (EU) basic identity information (name, homepage, email address, etc.), and store the user's unique ID as a cookie in the user's browser. Finally, let the browser redirect to the my-photo-print profile page.

Please note: This is just for simplicity. Please consider a more secure session mechanism for production environments.

The processing function of the profile page is profileHandler:

 // oidc-examples/my-photo-print/main.go // user profile页面func profileHandler(w http.ResponseWriter, r *http.Request) { fmt.Println("profileHandler:", *r) cookie, err := r.Cookie("my-photo-print.com-session") if err != nil { http.Error(w, "找不到cookie，请重新登录", 401) return } fmt.Printf("found cookie: %#v\n", cookie) mu.Lock() pf, ok := userProfile[cookie.Value] if !ok { mu.Unlock() fmt.Println("not found user:", cookie.Value) // 跳转到首页http.Redirect(w, r, "/", http.StatusSeeOther) return } mu.Unlock() // 渲染照片页面模板tmpl := template.Must(template.ParseFiles("profile.html")) tmpl.Execute(w, pf) }

We can see that the handler first checks whether the user ID exists in the cookie. If not, it redirects to the login page. If it does exist, it extracts the user's unique ID and uses it to find the user's profile information, and finally displays it on the web page:

At this point, we can see that the mechanism that entrusts the cloud disk authorization service to authenticate the user of my-photo-print and obtain the user's basic information is oidc.

Note: Once the user information is authenticated by the cloud disk authorization service, the RP can use various authentication mechanisms to manage EU users. For example, the RP can use session management technology (such as using session identifiers or browser cookies) to track the session status of the EU. If the EU accesses the RP application during the same session, the RP can identify the EU through the session identifier without having to authenticate again.

3. Summary

Through the above content, we have a more intuitive understanding of OpenID Connect (OIDC). Here is a summary:

• OIDC is an open standard protocol for identity authentication, built on top of OAuth 2.0 and compatible with OAuth 2.0.
• The OIDC protocol mainly involves three roles: RP (Relying Party), OP (Identity Provider), and EU (End User).
• After EU authenticates itself with OP through RP, RP can obtain EU's identity information. The entire process is highly similar to the authorization code process of OAuth 2.0.
• The key difference is that the token returned by the OP contains an ID_TOKEN (JWT format) in addition to the access_token.
• RP can obtain EU's unique identification and other information by parsing ID_TOKEN, and further obtain EU's detailed identity information through access_token.
• After RP obtains EU identity information, it can identify and manage EU through various mechanisms without the need for EU to repeatedly authenticate itself.

In general, OIDC uses the OAuth 2.0 process for identity authentication and provides EU identity information through the additional ID_TOKEN returned, which well meets RP's needs for EU identity management.

The source code involved in this article can be downloaded here [10].

4. References

• OIDC (OpenID Connect) Specification[11] - https://openid.net/specs/openid-connect-core-1_0.html
• Implementing an OpenID Connect user identity authentication protocol using OAuth 2.0 [12] - https://time.geekbang.org/column/article/262672