OAuth 2.0 and OpenID Connect

To decide which authentication flow is best for you, based on the type of application that you are building, you first need to understand OAuth 2.0 and OpenID Connect and how you can implement these two flows using the OneWelcome Identity Platform.

OAuth 2.0 compared to OpenID Connect

• The OAuth 2.0 protocol controls authorization to access a protected resource, like your web app, native app, or API service.

• The OpenID Connect protocol is built on the OAuth 2.0 protocol and helps authenticate users and convey information about them. It is also stricter compared to plain OAuth 2.0, for example in its scope definitions.

The OAuth 2.0 protocol provides API security through scoped access tokens. OAuth 2.0 enables you to delegate authorization, while the OpenID Connect protocol enables you to retrieve and store authentication information about your users. OpenID Connect extends OAuth 2.0 by providing user authentication, single sign-on (SSO), and single logout (SLO) functionality.

OAuth 2.0 terms

OAuth 2.0 is a standard that apps use to provide client applications with access. If you want to grant access to your application data in a secure way, then use the OAuth 2.0 protocol.

The OAuth 2.0 spec has four important roles:

• Authorization server: The server that issues the access token. In this case the OneWelcome Identity Platform is the authorization server.

• Resource owner: Normally your application's user that grants permission to access the resource server with an access token.

• Client: The application that requests the access token and then passes it to the resource server.

• Resource server: Accepts the access token and must verify that it's valid. In this case this is your application back end.

Other important terms include the following:

• An OAuth 2.0 grant is the authorization given (or granted) to the client by the user. Examples of grants are authorization code and client credentials. Each OAuth grant has a corresponding flow.

• The access token is issued by the authorization server, which is the OneWelcome Identity Platform, in exchange for the grant.

• The refresh token is an optional token that is exchanged for a new access token if the access token has expired.

OAuth 2.0 grant flow

A typical OAuth 2.0 grant flow looks like this:

1. Client requests authorization from the resource owner (usually the user).

2. If the user gives authorization, the client passes the authorization grant to the authorization server, which is the OneWelcome Identity Platform.

3. If the grant is valid, the authorization server returns an access token, possibly alongside a refresh or ID token.

4. The client now uses that access token to access the resource server.

Authorization server

At the core of both OAuth 2.0 and its OpenID Connect extension is the authorization server. Each authorization server has a unique issuer URI and its own signing key for tokens to keep a proper boundary between security domains. The OneWelcome Identity Platform is your authorization server.

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

OpenID Connect terms

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 client registration. The OneWelcome Identity Platform is OpenID Certified.

Although OpenID Connect is built on top of OAuth 2.0, the OpenID Connect specification uses somewhat different terms for the roles in the flows:

• OpenID provider is the authorization server that issues the ID token. In this case, the OneWelcome Identity Platform is the OpenID provider.

• End user is the user whose information is contained in the ID token.

• Relying party is the client application that requests the ID token.

• ID token is issued by the OpenID Provider and contains information about the end user in the form of claims.

• Claim is a piece of information about the 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 provides an ID token, in addition to any access or refresh tokens.

Choosing an OAuth 2.0 flow

The OAuth flow that you use depends on your use case. The table below maps application types to OAuth 2.0 flows. If you need more information, keep reading for help with choosing an OAuth flow based on the type of token that you need, or the type of client application that you are building.

OAuth 2.0 flows by application type

The table shows which OAuth 2.0 flow to use for the type of application that you are building:

Type of Application	OAuth 2.0 Flow
Server-side (Web)	Authorization code flow
Single-page application	Authorization code flow with PKCE
Mobile apps	OneWelcome Identity Platform Mobile SDK or authorization code flow with PKCE
Service	Client credentials

Does your application need an ID token?

Any OAuth flow provides an access token, but some flows are not supported by OIDC and these flows do not provide an ID token.

	Access Token	ID Token
Authorization code	Yes	Yes
Authorization code with PKCE	Yes	Yes
Client credentials	Yes	No

Authorization code flow

The authorization code flow is best suited to server-side apps. The apps should be server-side because the request that exchanges the authorization code for a token requires a client secret (or JSON Web Key Set (JWKS)), which must be stored in your client. The server-side app requires a user, because it relies on interaction with the user's web browser, which redirects the user and then receives the authorization code.

Client credentials flow

The client credentials flow is intended for server-side (confidential) client applications with no user, which normally describes machine-to-machine communication. The application must be server-side, because it must be trusted with the client secret. It can't be used by an actual user because the credentials are hard-coded. It involves a single, authenticated request to the /token endpoint, which returns an access token.

Approved IETF specifications

The documentation refers to the following approved IETF specifications:

RFC6749 - OAuth 2.0 The OAuth 2.0 Authorization Framework

RFC7662 Token Introspection OAuth 2.0 Token Introspection

RFC 7009 Token Revocation OAuth 2.0 Token Revocation

RFC7636 PKCE Proof Key for Code Exchange by OAuth Public Clients

RFC6750 Bearer tokens The OAuth 2.0 Authorization Framework: Bearer Token Usage

Draft IETF specifications

The documentation also refers to the following draft IETF specifications:

OAuth device OAuth 2.0 Device Flow for Browser-less and Input Constrained Devices (draft, dd. March 2017)

OAuth Client Assertions Client Authentication and Authorization Grants (draft, dd. October 2014)

OAuth Native Apps OAuth 2.0 for Native Apps (draft, dd. April 2017)

OAuth Token Exchange OAuth 2.0 Token Exchange

Furthermore, the documentation refers to OIDC OpenID Connect website.