OAuth 2.0 & OpenID Connect Overview and Concepts

Authentication and authorization are essential to application development. Whether our customers are developing an internal IT app for their employees, building a portal for their partners, or exposing a set of APIs for developers building apps, customers and partners need an industry standard, scalable and performant framework for authentication and authorization.

With 1Kosmos, customers can controll access to the application using both OAuth 2.0 and OpenID Connect. Customers can use 1Kosmos as their authorization server to retain all of their user information and grant users tokens to control their authorization and authentication.

OAuth 2.0

OAuth 2.0 is a modern authentication framework that delegates authentication to an external identity provider, an IdP, like Google, Facebook, Apple, or Microsoft. A user logs on to the chosen provider instead of creating yet another password for the application they are attempting to access.

Developers can augment the user journey and enrich the experience with additional context and information consented to, and shared by the providers. 1Kosmos has implemented the OAuth specification to simplify the development process by abstracting the implementation details of OAuth for developers.

The OAuth 2.0 authorization framework specified in RFC 6749, The OAuth 2.0 Authorization Framework, defines the protocol for a third-party application to obtain limited access to user data, either on behalf of the user, a trusted "delegate" of the user, or the application's own behalf. The OAuth 2.0 protocol provides API security through scoped JWT tokens called access tokens. OAuth 2.0 enables you to delegate authorization, while OIDC enables you to retrieve and store authentication information about your end users.

Actor	Description
User or Resource Owner (RO)	The owner of the data or APIs. The owner, typically an end user, uses a web- or mobile-based browser to communicate with the client.
Client	The third-party application that wants to obtain access to the data or APIs. The client makes requests on behalf of the user and with their consent.
Authorization Server (AS)	The authorization service that authenticates the user or the client and issues access tokens to the client. Access tokens prove that the end user authorized the client to act on their behalf over specific "scopes" or subsets of their data for a limited amount of time.
Resource Server (RS)	The service hosting the protected data. The resource server must be able to validate the tokens issued by the authorization server. A website protected by a web or a Java agent can act as the resource server.

There are two main types of authentication flows supported by 1Kosmos:

• The OAuth 2.0 protocol controls authorization to access a protected resource, like your web app, native app, or API service.
• The OpenID Connect (OIDC) protocol is built on the OAuth 2.0 protocol and helps authenticate users and convey information about them.

OIDC extends OAuth 2.0 by providing user authentication and single sign-on (SSO) functionality.

1Kosmos as an OAuth 2.0 Authorization Server

At its core, an authorization server is simply an engine for minting OpenID Connect or OAuth 2.0 tokens. An authorization server is also used to apply access policies. Each authorization server has a unique issuer URI and its own signing key for tokens to keep a proper boundary between security domains.

Customers can use an authorization server to perform Single Sign-On (SSO) with 1Kosmos for their OpenID Connect apps. They can also use an authorization server to secure their own APIs and provide user authorization to access their web services.

OpenID Connect is used to authenticate users with a web app. The app uses the ID token that is returned from the authorization server to determine if a user is authenticated and to obtain profile information about the user, such as their username or email.

OAuth 2.0 can also be used for endpoint security, ie., authorize user access to an API endpoint. An access token is used by the resource server to validate a user's level of authorization/access. That is a complicated way of saying that a user's grant-level or entitlements can be embedded inside a Java Web Token (JWT) and inspected later on by "entities" interested in corroborating access. When using OpenID Connect or OAuth, the authorization server authenticates a user and issues an ID token and/or an access token. In this document, id_token notation is used. The id_token specifically contains the user information details such as Personally Identifiable Information (PII) whereas the access_token is primarily used for holding verifiable "metadata" about the authorization level of the user, such as the "issuer" name and "audience" for whom the token was intended.

It is important to note that no access can be granted to a user, or their private information shared with a service or an application without their consent.

The full OAuth 2.0 code grant flow is represented here:

The compacted OAuth 2.0 grant flow looks like this:

1. Client requests authorization from the resource owner (usually the user).
2. If the user gives consent, the client passes the authorization grant to the authorization server (in this case 1Kosmos).
3. If the grant is valid, the authorization server returns an access token, possibly alongside a refresh token, an id_token, or both.
4. THe client now uses that access token to access the resource server.

At the core of both OAuth 2.0 and its OpenID Connect extension is the authorization server. An authorization server is simply an OAuth 2.0 token minting engine. Each authorization server has a unique issuer URI and its own signing key for tokens to keep a proper boundary between security domains. In the context of this guide, 1Kosmos is the authorization server.

The authorization server also acts as an OpenID Connect Provider, which means you can request ID tokens in addition to access tokens from the authorization server endpoints.

End User Journeys for OAuth 2.0

Authentication by Redirection

Redirection flow is an interactive sign-in flow that grants authentication control to 1Kosmos by redirecting the user to a 1Kosmos hosted sign-in page. The page is hosted in our Administration Portal we call AdminX.

Embedded Authentication

This is a scenario that is suited to developers. In this flow, an end user is not redirected to 1Kosmos. Instead, the application retains authentication control using a client embedded SDK, or directly via the 1Kosmos Platform OAuth 2.0 API calls. A key thing to note here is that in general, the method of delegating user sign-in interaction (redirect authentication) is generally preferred for many reasons that span from security to user experience.

When using OIDC, redirect authentication through AdminX is considered the easiest and most secure means of integration. The user or system is redirected to 1Kosmos for credential verification and is then provided authenticated access to the client application.

Consider, for example, when an organization uses 1Kosmos as its Identity Provider. A user tries to access the organization's on-site or cloud-based application (for example, email) and is redirected to the corporate Identity Provider, 1Kosmos, to provide sign in and authentication.

After the user is authenticated, 1Kosmos provides a token or assertion to the original application to grant the user access. 1Kosmos also creates an AdminX session for the authenticated user. Using SSO with this existing 1Kosmos session, the user is automatically signed in to any other of the organization's Service Provider applications (CRM, IT, HR, and so on).

OpenID Connect

OpenID Connect is an authentication standard built on top of OAuth 2.0. It adds an additional token called an id_token. OpenID Connect also standardizes areas that OAuth 2.0 leaves up to choice, such as scopes, endpoint discovery, and dynamic registration of clients. Although OpenID Connect is built on top of OAuth 2.0, the OpenID Connect Specification uses slightly different terms for the roles in the flows:

1. OpenID Provider: The authorization server that issues the id_token. In this case, 1Kosmos is the OpenID provider.
2. end user: The end user's information that is contained in the id_token.
3. relying party: The client application that requests the id_token from 1Kosmos.
4. id_token: The token issued by the OpenID Provider and contains information about the end user in the form of claims.
5. claim: The claim is a piece of information about the end user.

The high-level flow looks the same for both OpenID Connect and regular OAuth 2.0 flows.

The primary difference is that an OpenID Connect flow results in an id_token, in addition to any access or refresh tokens.

Recommended Flow by Application Type

The table shows you which OAuth 2.0 flow to use for the type of application that customers will be building.

Type of Application	OAuth 2.0 Flow / Grant Type	Access Token?	id_token?
Server-side (aka Web)	Auth Code	✅	✅
Single-Page Application	Implicit	✅	✅
Native	Auth Code with PKCE	✅	✅
Trusted	Resource Owner Password	✅	✅
Service	Client Credentials	✅	❌

Guidance for Picking OAuth 2.0 Flow

The type of OAuth 2.0 flow depends on what kind of client you are building. This flowchart can quickly help you decide which flow to use.

A client application is considered public when an end user could possibly view and modify the code. This includes Single-Page Apps (SPAs) or any mobile or native applications. In both cases, the application can't keep secrets from malicious users.

Is your client a SPA or native?

If your client application is a SPA you should use the Authorization Code flow with PKCE, or the Implicit flow.

If your client application is a native application, you should use the Authorization Code flow with PKCE.

For security purposes, 1Kosmos only supports the Authorization Code and Authorization Code flow with PKCE flows. For Single-Page Applications, we recommended trying the Authorization Code with PKCE flow first.

Does the client have an end user?

If your client application is running on a server with no direct end user, then it can be trusted to store credentials and use them responsibly. If your client application is only doing machine-to-machine interaction, then you should use the Client Credentials flow.

Is your app high-trust?

If you own both the client application and the resource that it's accessing, then your application can be trusted to store your end user's username and password. These types of apps are considered "high-trust". Because of the high degree of trust required, you should only use the Resource Owner Password flow if other flows are not viable.

If your app is not high-trust, you should use the Authorization Code flow.