OIDC

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol, designed to provide secure and standardized user authentication and authorization in modern web applications.

OIDC enables applications to verify the identity of users, obtain user profile information, and securely authenticate users using various identity providers, such as Google, Facebook, or Microsoft.

With OIDC, developers can delegate the responsibility of user authentication to trusted identity providers, reducing the complexity of managing user credentials. By leveraging JSON Web Tokens (JWTs) and standardized protocols, such as OpenID Connect Discovery, OIDC simplifies the integration of identity services into applications and ensures interoperability between different identity providers and relying parties.

With its emphasis on user-centric authentication and secure identity federation, OIDC has become a widely adopted standard for implementing robust and scalable identity solutions in the digital era.

Key Points

• OIDC Overview:
  • Extends OAuth 2.0 with an identity layer.
  • Returns an ID Token (JWT) containing user information alongside the Access Token.
  • Enables clients to verify user identity.
• Key Differences from OAuth 2.0:
  • Renamed roles: Authorization Server -> OIDC Provider (IDP), Client -> Relying Party (RP).
  • ID Token is always a JWT.
  • Standardized scopes: openid, profile, email.
  • ID Token claims: sub, iss, aud, iat, exp, acr, email.
• OIDC Grant Flows:
  • Uses the same grant types as OAuth 2.0.
  • ID Token is primarily used with Authorization Code and PKCE flows.
• OIDC Endpoints:
  • Userinfo Endpoint: Retrieves user claims using an Access Token.
  • JWKS Endpoint: Provides public keys for JWT verification.
  • /.wellknown Endpoint: Returns OIDC metadata about the IDP.
• Single Sign-On (SSO):
  • Allows users to access multiple applications with a single set of credentials.
  • Benefits: Enhanced security, increased productivity, reduced IT costs, improved user experience.
  • OIDC is a popular standard for implementing SSO.
• Modern SSO with OIDC:
  • OIDC provider acts as the central authentication authority.
  • Applications (clients) interact with the OIDC provider for authentication.
  • Sessions are managed at both the client application and OIDC provider levels.
  • Achieves SSO by leveraging the OIDC provider's session.

What OIDC (OpenID Connect) is

OIDC stands for "OpenID Connect". It is built on top of OAuth 2.0 protocol with an added Identity Layer, meaning OIDC is a superset of OAuth 2.0. In simple words, it allows another token - ID Token (Identity Token) to be returned together with the Access Token. While Access Token is used to access some resources, ID Token itself contains the User Information who has authenticated to the Authorization Server.

Why OIDC

Generally speaking, the whole point of OAuth 2.0 is for clients to get an Access Token so that it can access some resources. This works well for privilege delegation like explained in OAuth 2.0 chapters.

However, that Access Token does NOT contain any User Information (e.g. username, email, role...) who has authenticated to the Authorization Server and this User Information is often critical for a lot of functions in a system. Hence, after the OAuth 2.0 protocol came out and became popular, technology groups started to realize that there is a strong need to obtain that User Information somewhere during the process of running OAuth 2.0 flows.

Then the idea is why not just add another token that contains the User Information and return it together with the Access Token, as the OAuth 2.0 protocol is already popular? So the ID Token is added when Access Token is returned. Beyond just adding the ID Token, we need to make it more comprehensive and become a standard so that everyone can follow it and hence, the birth of OIDC.

Understanding OIDC

Since OIDC is OAuth 2.0 under the hood, the core parts are the same for both two (such as grant types). Yet, there are still some naming changes and extensions in OIDC compared to OAuth 2.0.

1. Roles

The Authorization Server in OAuth 2.0 is renamed as OIDC Provider (also called Identity Provider or simply IDP).

The Client in OAuth 2.0 is renamed as Relying Party (RP).

Some of the terms are used interchangeably as in nature, they are the same.

2. Use of JWT

In OAuth 2.0, JWT is pretty much the go-to format for Access and Refresh Tokens. In OIDC, an ID Token is always a JWT token. Nowadays, all tokens are pretty much JWT tokens and that includes Access Token, ID Token and Refresh Token.

3. Standardized Scope

Scope in OAuth defines the level of privileges of an Access Token. When a Client registers with Authorization Server, it needs to define the available scope list and there is no standard on that, meaning any client can define whatever values they want.

OIDC addresses scopes to the ID Token specifically. It provides some standard frequently used scopes while allowing custom scopes. Remember scope can be a list of string values and whenever a scope value is specified, the corresponding claims (or attributes) are returned in the ID Token.

Here are a list of the predefined standard scopes:

4. ID Token

The ID Token is JWT format and its payload includes a list of claims (attributes). Here are some basic ones.

For a more detailed list, you can check https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

5. OIDC Grant Flows

The grant flow for OIDC is the same with OAuth 2.0 as described previously.

• Authorization Code
• Client Credentials
• PKCE
• Device Code
• Refresh Token
• Implicit (deprecated)
• User Password (deprecated)

Those flows can be categorized into two groups: human-to-server and server-to-server

Since ID Token is addressed to a User, the ID Token won't be returned in the server-to-server call, as there is no User authentication happening.

From the list above, Authorization Code and PKCE grant flows are the main ones used to get an ID Token. Although Device Code flow involves user authentication, ID Token is NOT usually used in the flow. Client Credentials and Refresh Token flows are server-to-server calls, so no ID Token will be returned. Implicit and User Password flows involve User, but is deprecated due to security concerns and shouldn't be used for modern platforms.

6. Endpoints

Besides the original OAuth 2.0 endpoints (e.g. token introspection), there are some other endpoints worth mentioning as well.

Userinfo Endpoint

New to OIDC this endpoint allows you to make a request using an appropriate Access Token to retrieve identity information (claims) about the authenticated User. Here is an example:

{
   "sub":"uid4BTXdCDI6TV4m3g3",
   "name":"John Doe",
   "first_name":"John",
   "last_name":"Doe",
   "locale":"en-US",
   "updated_at":1311280970,
   "email":"john.doe@example.com",
   "email_verified":true,
   "address":{
      "street_address":"123 xxx Blvd.",
      "locality":"Boston",
      "region":"MA",
      "postal_code":"02115",
      "country":"US"
   },
   "phone_number":"+1 (777) 888-9999"
}

JWKS (Json Web Key Set ) Endpoint

JWKS (pronounced 'jawks') is a set of keys containing the public keys used to verify any JWT issued by the Authorization Server and signed using the asymmetric encryption algorithm (e.g. RS256). Below is an example where the first entry is shown:

{
   "keys":[
      {
         "alg":"RS256",
         "kty":"RSA",
         "use":"sig",
         "x5c":["MIIC+DCCAeCgAwIBABIGjYW6hFpn2VBAMTGGN1c3Rvb..."],
         "n":"yeNlzlub9codqEztjfU_SPCT1Axz6if3lHpq_g4Sz-cbe4....",
         "e":"AQAB",
         "kid":"NjVBRjY5MDlCMUIwNzU4RTA2QzZFM",
         "x5t":"NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDA"
      }
   ]
   ...
}

Each property in the key is defined by the JWK spec

The /.wellknown Endpoint

The .wellknown endpoint (don't miss the dot) returns OIDC metadata about the Authorization Server or OIDC Server. This endpoint usually does NOT need any authentication. Here is an example:

{
   "issuer":"https://authorization-server.com",
 "authorization_endpoint":"https://authorization-server.com/oauth/authorize",
   "token_endpoint":"https://authorization-server.com/oauth/token",
   "userinfo_endpoint":"https://authorization-server.com/oauth/userinfo",
   "registration_endpoint":"https://authorization-server.com/oauth/clients",
   "jwks_uri":"https://authorization-server.com/jwks",
   "response_types_supported":[
      "code",
      "code id_token",
      "code token",
      "code id_token token",
      "id_token",
      "id_token token"
   ],
   "response_modes_supported":[
      "query",
      "fragment",
      "form_post"
   ],
   "grant_types_supported":[
      "authorization_code",
      "implicit",
      "refresh_token",
      "password"
   ],
   "subject_types_supported":[
      "public"
   ],
   "id_token_signing_alg_values_supported":[
      "RS256"
   ],
   "scopes_supported":[
      "openid",
      "email",
      "profile",
      "address",
      "phone"
   ],
   "token_endpoint_auth_methods_supported":[
      "client_secret_basic",
      "client_secret_post",
      "client_secret_jwt",
      "none"
   ],
   "claims_supported":[
      "iss",
      "ver",
      "sub",
      "aud",
      "iat",
      "exp",
      "jti",
      "auth_time",
      "amr",
      "idp",
      "nonce",
      "name",
      "preferred_username",
      "first_name",
      "last_name",
      "email",
      "email_verified",
      "profile"
   ],
   "introspection_endpoint":"https://authorization-server/oauth/introspect",
   "introspection_endpoint_auth_methods_supported":[
      "client_secret_basic",
      "client_secret_post",
      "client_secret_jwt",
      "none"
   ],
   "revocation_endpoint":"https://authorization-server/oauth/revoke",
   "revocation_endpoint_auth_methods_supported":[
      "client_secret_basic",
      "client_secret_post",
      "client_secret_jwt",
      "none"
   ]
}

SSO (Single Sign-On)

SSO has been prevalent in organizations for years, but its importance is a lot of times overlooked. As the big trend is moving to cloud and taking advantage of third-party services, seamless and secure access to multiple applications is essential for maintaining operation efficiency and a smooth customer experience. This is done via SSO.

SSO itself is an authentication mechanism to allow users to securely access multiple applications using just one set of credentials. Furthermore, with SSO, a user doesn't need to sign on repeatedly to different applications, meaning the user needs to sign on just once and he will gain access to all authorized applications, websites and data from an organization or multiple related organizations.

Why SSO is Important

There are many benefits of using SSO, such as enhanced security, increased productivity, lowered IT costs and improved user experience.

Enhanced Security

Cybercriminals usually target usernames and passwords. In other words, the more accounts a user has, the more management overhead and vulnerabilities it has. Since users only need to remember one credential, they tend to use more complex and secure passwords.

A usual misconception about SSO is that if this only account is stolen, the whole system is compromised. While that seems true at first glance, the reality is that with good practices, the probability of compromising that account is significantly lowered.

A great strategy is to use MFA (Multi-Factor Authentication) with SSO. MFA requires a user to present at least two different types of means to authenticate himself. For example, a username/password and a push notification to a cell phone.

As a result, the security benefits of SSO far outweighs its issue.

Increased Productivity

SSO increases employee productivity by reducing the time they spend signing on and managing passwords. More often than not, an employee needs to interact with multiple applications in the day-to-day work. While he is spending time logging into different accounts, remembering them and retrieving them could be some other overheads, plus changing and resetting passwords.

The time and effort can be saved with one account.

Lowered IT Costs

Studies have shown that more than 50% of help desk calls are about password issues. In other words, the more passwords a user has, the more work the IT help desk will have. Furthermore, if an organization has some specific password policy that requires a long and complicated password, the burden could be increased more. SSO will help in reducing this kind of cost.

SSO Improves User Experience

With the move to cloud, employees are starting to use more apps in the work. A lot of accounts could be frustrating to deal with. Signing-in once not only increases productivity, it enhances employees' job satisfaction as well.

SSO also improves customer experience. Sometimes, a customer abandons his cart simply because of a forgotten password or password reset issue. SSO alleviates this kind of issue and provides a seamless experience.

OIDC as a SSO Standard

There are two popular SSO standards that are popular for SSO: SAML and OIDC.

SSO doesn't have to be based on standards, but using standards has a lot of benefits and it has become a general practice in industry to use SAML or OIDC for SSO.

We know that OAuth 2.0 by itself is more of a privilege delegation protocol, and OIDC adds an identity layer on top of OAuth 2.0, which makes it very suitable for SSO. SAML is another popular SSO standard, especially in enterprise SSO. We will focus on OIDC in this post.

Modern SSO Integration Pattern with OIDC

Let's take a look at an example to understand how modern SSO works with OIDC.

In the below diagram:

• An OIDC provider acts as the core of the SSO system within an enterprise intranet
• There are internal and external apps (Client) that are interacting with this system
• API1 and API2 are API resources (Resource Server) that client application can access and they have their own databases
• The external/internal application can be either a public client or a confidential client depending on the settings of the context
• The OIDC provider is connected to an enterprise directory where the user accounts are stored
• Users can be either within intranet or external facing

Authorization Code Flow

An example Authorization Code flow would be that a user starts to use Internal App1, the latter redirects the user to OIDC Provider for authentication. After the user authenticates, the OIDC provider returns Access Token and ID Token. Internal App1 extracts user information from the ID Token and processes some business logic. Then the Internal App1 sends a request with the Access Token to the API1. API1 verifies the Access Token and returns the API resources to Internal App1. The app processes the resources and further assists user operations.

Client Credentials Flow

Another example with Client Credentials flow would be that API1 needs to request some resources from API2. This would be a server-to-server (or machine-to-machine) call. API1 first gets an Access Token (No ID Token) from the OIDC server and then sends the request along with the Access Token to API2. API2 verifies the Access Token and returns the resources.

Sessions and How SSO is Achieved

Usually the client applications manage user sessions by themselves, meaning each client application will maintain a user session for its own and separate client apps have separate user sessions. This is a pure client application session and has nothing to do with the OIDC provider. The good thing for this kind of app session is that whenever the user comes back to the same client app where a user session exists, the user doesn't need to authenticate anymore.

However, if no session exists for the client application, it will redirect the user to the OIDC provider for authentication and once authenticated, the OIDC server will create a user session too. Besides that, the OIDC provider will return an ID Token to the client application. Then the client app extracts user info from the ID Token so that it knows which user it is and hence creates a client app session for that user.

Next, when the user tries to access another client app, he is redirected to the OIDC provider again. But this time, since the user has already authenticated to the OIDC provider (in the last transaction) and a user session does exist, the user doesn't need to authenticate anymore. The Access Token and ID Token will be directly returned to the client app.

In all cases, as long as the apps are interacting with the same OIDC provider, only one account is needed and only one login is needed during a certain time. This is how SSO is achieved.