OIDC, short for OpenID Connect, is an identity verification protocol based on OAuth 2.0. Before understanding OIDC, you need to first understand the relevant definitions of OAuth 2.0.
Authentication and Authorization
First, we need to distinguish between authentication and authorization.
1. Authentication refers to the process of identity verification, that is, verifying "who you are."
2. Authorization refers to the process of granting permissions, that is, verifying "what you can access."
Take a real-life example: When we board a plane, we need to present a boarding pass and a ticket. The boarding pass proves our identity, and the ticket proves which class we can travel in. In practical scenarios, authentication and authorization are interdependent. Understanding these two concepts helps us understand the concepts related to OIDC.
Note:
OAuth 2.0 is an authorization protocol and cannot solve identity verification problems. OIDC is the authentication protocol that truly implements Single Sign-On (SSO).
Password and Token
Assume the following scenarios:
1. When a user Zhang San needs to access his email system, the email system needs to verify Zhang San's username and password.
2. Suppose another business system, OA, also wants to collect emails on behalf of Zhang San.
The problem is as follows: Before OAuth 2.0, the common practice was for Zhang San to share his password with the OA system. This poses major security issues:
1. How can you control the access permissions of the OA system, and how can you prevent the OA system from sending emails arbitrarily in Zhang San's name?
2. How can you revoke the OA system's permission to access emails?
OAuth 2.0 was created to solve this problem. It introduces the concepts of "authorization" and access token.
Both tokens and passwords can enable the OA system to access the email system, but they differ in the following ways:
1. Tokens are short-lived and expire automatically, and users cannot modify them. Passwords are generally long-lived and remain unchanged unless users modify them.
2. A token can be revoked by the data owner and becomes invalid immediately.
3. Tokens have a permission scope. For example, a token can only receive emails but cannot send them. For network services, read-only tokens are more secure than read-write tokens. Passwords generally have full permissions.
OAuth 2.0 Authorization Types
According to RFC 6749, OAuth 2.0 specifies token issuance in great detail, dividing it into authorization grant types such as Authorization Code, Implicit, Password, and Client Credentials Grant. Authorization Code
1. After a user clicks a link on the service provider (SP) website, the browser is redirected to the identity provider (IdP) website, where the user authorizes the SP website to use their data. The following is an example link for redirecting from the SP website to the IdP website.
https://www.idp.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read
The response_type parameter indicates that an authorization code (code) is required.
The client_id parameter lets the IdP know which system is requesting user information.
The redirect_uri parameter is the redirect URL after the IdP website accepts or rejects the request.
The scope parameter indicates the requested authorization scope.
2. After the redirect, the IdP website prompts the user to log in and then asks whether the user agrees to grant authorization to the SP website. After the user agrees, the IdP website redirects back to the URL specified by the redirect_uri parameter. During the redirect, an authorization code is returned.
https://www.sp.com/callback?code=AUTHORIZATION_CODE
3. After the SP website obtains the authorization code, it requests a token from the IdP website on the server side.
Note:
The request must be initiated by the server, and CLIENT_SECRET must not be exposed to the frontend page.
OAuth generally uses Basic Auth to transmit client_id and client_secret. It also supports placing client_id and client_secret in a form. Both methods are demonstrated here, but this does not mean you must use both simultaneously in real scenarios. The same applies to the grant types described below and will not be reiterated.
curl \\
-X POST https://www.idp.com/oauth/token \\
-H 'Content-Type:application/x-www-form-urlencoded' \\
-H 'Authorization:Basic {CLIENT_ID: CODE_VERIFY}' \\
-d '{ grant_type=authorization_code&
code={code}&
redirect_uri=https://www.sp.com/callback
client_id=CLIENT_ID&
code_verifier=CODE_VERIFY&
grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=CALLBACK_URL
}'
4. After successful verification on the IdP server, the following response is returned.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "xxxxxxx",
"refresh_token": "xxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600
}
Implicit
The implicit grant type skips the authorization code step and directly returns an access token. All steps are completed in the browser, and the token is visible to visitors.
1. Same as the authorization code mode, initiate an authorization request.
https://www.idp.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read
2. After the IdP verifies the user's permissions, it redirects back to the SP website with a token.
https://www.sp.com/callback#access_token=2YotnFZFEjr1zCsicMWpAA&token_type=Bearer&expires_in=3600
Attention:
The character following "callback" is a # character, not a ? character.
Password
1. The Resource Owner Password Credentials Grant skips the browser authorization step and directly requests a token by sending the username and password.
curl \\
-X POST https://www.idp.com/oauth/token \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
-H 'Authorization: Basic {CLIENT_ID: CLIENT_SECRET}' \\
-d '{grant_type=password&username=USERNAME&password=PASSWORD}'
2. The IdP server returns the following response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "xxxxxxx",
"refresh_token": "xxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600
}
Client Credentials Grant
Note:
The Client Credentials Grant is generally suitable for command-line apps without a user interface.
1. Request a token.
curl \\
-X POST https://www.idp.com/oauth/token \\
-H 'Content-Type:application/x-www-form-urlencoded' \\
-H 'Authorization:Basic {CLIENT_ID: CLIENT_SECRET}' \\
-d '{grant_type=client_credentials}'
2. The IdP server returns the following response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "xxxxxxx",
"refresh_token": "xxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600
}
PKCE
The authorization code mode seems quite good, with complete features and a rigorous flow. However, it relies on the assumption that the server's client_secret will not be compromised.
When certain clients make requests, some security issues may arise.
Native app
For client apps such as Android apps, the source code can be decompiled, making the client_secret highly susceptible to leakage.
Single-Page Application (SPA)
In a single web app, the entire source code resides in the browser, making it impossible to securely store the client_secret.
Therefore, a new mode is introduced: Proof Key for Code Exchange (PKCE). According to the latest protocol security recommendations, the traditional implicit mode is no longer recommended for SPAs. Instead, the more secure PKCE mode is recommended. The difference between PKCE and the authorization code mode is that the concept of client_secret does not exist. The SP app needs to first generate a code_verifier and then apply urlEncodeSHA256 to it to obtain the code_challenge.
1. After a user clicks a link on the SP website, the browser is redirected to the IdP website.
https://www.idp.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read&code_challenge=CODE_CHALLENGE
Attention:
Compared with the authorization code mode, an additional CODE_CHALLENGE is introduced here.
2. After successful login at the IdP, the browser is redirected back with an authorization code.
https://www.sp.com/callback?code=AUTHORIZATION_CODE
3. After the SP website obtains the authorization code, it requests a token from the IdP website on the server side.
curl \\
-X POST https://www.idp.com/oauth/token \\
-H 'Content-Type:application/x-www-form-urlencoded' \\
-H 'Authorization:Basic {CLIENT_ID: CODE_VERIFIER}' \\
-d '{ grant_type=authorization_code&
code={code}&
redirect_uri=https://www.sp.com/callback
client_id=CLIENT_ID&
code_verifier=CODE_VERIFIER&
grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=CALLBACK_URL
}'
Note:
Same as the authorization code mode, client_id and code_verifier are generally transmitted using Basic Auth.
However, client_id and code_verifier can also be included in the form body. Both methods are described here, but this does not mean you must use both simultaneously in real scenarios.
4. After successful verification on the IdP server, the following response is returned.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "xxxxxxx",
"refresh_token": "xxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600
}
Note:
The server applies the same urlEncodeSHA256 processing to the code_verifier and compares the result with the previously received code_challenge.
OIDC
As mentioned earlier, authentication and authorization are two different concepts. Note that the OAuth protocol is only an authorization protocol and does not involve identity verification.
OIDC adds an identity verification layer on top of OAuth 2.0.
OIDC adds the following content:
The token API adds the return of id_token: when a token is obtained, the API must return not only access_token and refresh_token but also id_token, which is a JWT-format token that carries user information.
The user_info API is added: you can use access_token to call the user_info API to obtain user information.
The OIDC Discovery endpoint is defined: the OIDC description file.
id_token
The OIDC specification explicitly defines the id_token format in detail, and it must be in JWT format.
The OIDC server must provide an RSA public key for clients to verify the JWT signature.
The id_token carries basic user information. The client can directly use information in the id_token, or it can use the access_token to call the user_info API to obtain user information.
user_info API
In addition to using the id_token to identify users, the client can also call the user_info API to obtain user information.
curl \\
-X GET https://www.idp.com/oauth/user_info \\
-H 'Content-Type:application/json ' \\
-H 'Authorization:Bearer {access_token}' \\
Note:
Use the Bearer Token method here.
For OIDC clients, the attributes of the returned user information are strictly standardized.
{
"sub": "us-xxxx",
"name": "Zhang San",
"preferred_username": "zhangsan",
"email": "zhangsan@test.com",
"email_verified": true,
"phone_number": "123456789001",
"phone_number_verified": true
}