Authentication Model¶

Overview¶

Under the authentication model we include all domain models required to manage the identification and authentication process based on OpenIdConnect. For this reason, the authentication model contains information highly related to deployment and environment; how, clients interacts with resources and where those clients and resources are deployed is described by this model. References to URIs and Origins are quite common here; and we are persisting these information in database (authentication schema).

There are four domain models: api resources, identity resources, clients and persisted grants.

However, for continuing is important to define some terminology and ensure some technical background.

The oAuth 2.0 Authorization Framework¶

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Why not just oAuth¶

OAuth has not notion of identity; actually, “oAuth is an access granting protocol, also known as delegation” . This is managed with an access token. Let’s seen an example:

“Mark grants access to Paul to access to Scott’s profile. That doesn’t mean that Mark is Paul, or Paul is Scott”. However, some sites does this mistakes and allows to impersonate users.

To fulfil this gap, OpenID Connect introduces the concept of ID Token.

OpenID Connect 1.0¶

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

OpenID Connect allows clients of all types, including web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and session management, when it makes sense for them.

Duende IdentityServer¶

Duende IdentityServer v6 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. This is the base open source project we have used to implement our “identity server” (authentication server). Different literature uses different terms for describing the same role that this service provides: security token service, identity provider, authorization server, IP-STS and more. But they are in a nutshell all the same: a piece of software that issues security tokens to clients.

It enables the following features in our applications:

• Authentication as a Service. Centralized login logic and workflow for all of your applications (web, native, mobile, services). Duende IdentityServer is an officially certified implementation of OpenID Connect.
• Single Sign-on / Sign-out. Single sign-on (and out) over multiple application types.
• Access Control for APIs. Issue access tokens for APIs for various types of clients, e.g. server to server, web applications, SPAs and native/mobile apps.
• Federation Gateway. Support for external identity providers like Azure Active Directory, Okta, JumpCloud, etc. This shields your applications from the details of how to connect to these external providers.
• Focus on Customization. The most important part - many aspects of Duende IdentityServer can be customized to fit your needs. Since Duende IdentityServer is a framework and not a boxed product or a SaaS, you can write code to adapt the system the way it makes sense for your scenarios.
• Mature Open Source. Duende IdentityServer uses the permissive Apache 2 license that allows building commercial products on top of it. It is also part of the .NET Foundation which provides governance and legal backing.

For .Net Framework applications we are using components from IdentityServer3; as this is the version targeting .net framework.

Terminology¶

This section is adapted from https://docs.duendesoftware.com/identityserver/v6/overview/terminology/.

User¶

A user is a human that is using a registered client to access resources.

Client¶

A client is a piece of software that requests tokens from authentication server - either for authenticating a user (requesting an identity token) or for accessing a resource (requesting an access token). A client must be first registered with authentication server before it can request tokens. Examples for clients are web applications, native mobile or desktop applications, SPAs, server processes etc.

Resources¶

Resources are something you want to protect with Duende IdentityServer - either identity data of your users, or APIs. Every resource has a unique name - and clients use this name to specify to which resources they want to get access to.

Identity data: claims¶

Identity information (aka claims) about a user, e.g. name or email address.

Identity resources are data like user ID, name, or email address of a user. An identity resource has a unique name, and you can assign arbitrary claim types to it. These claims will then be included in the identity token for the user. The client will use the scope parameter to request access to an identity resource.

The OpenID Connect specification specifies a couple of standard identity resources. The minimum requirement is, that you provide support for emitting a unique ID for your users - also called the subject id. This is done by exposing the standard identity resource called openid. Supported scopes defined by specification are openid, email, profile, telephone, and address; however, we are just using openid and profile.

APIs¶

APIs resources represent functionality a client wants to invoke - typically modelled as Web APIs, but not necessarily. To allow clients to request access tokens for APIs, we need to define API resources; and for getting access tokens for APIs, we also need to register them as a scope. So, at least each resource needs to define one scope.

Tokens¶

Identity Token¶

An identity token represents the outcome of an authentication process. It contains at a bare minimum an identifier for the user (called the sub aka subject claim) and information about how and when the user authenticated. It can contain additional identity data.

Access Token¶

An access token allows access to an API resource. Clients request access tokens and forward them to the API. Access tokens contain information about the client and the user (if present). APIs use that information to authorize access to their data.

Grant Types¶

Grant types are a way to specify how a client wants to interact with the authentication server. The OpenID Connect and OAuth 2 specs define the following grant types: Implicit, Authorization code, Hybrid, Client credentials, Resource owner password, Refresh tokens and Extension grants.

In our current implementation we are using client credentials, authentication code and hybrid; in the first implementation we were using implicit as well, but we stopped using it due to security risks. So we will focus on those grant types:

Client credentials¶

This is the simplest grant type and is used for server to server communication - tokens are always requested on behalf of a client, not a user. With this grant type you send a token request to the token endpoint, and get an access token back that represents the client. The client typically has to authenticate with the token endpoint using its client ID and secret.

Authorization code¶

Authorization code flow was originally specified by OAuth 2, and provides a way to retrieve tokens on a back-channel as opposed to the browser front-channel. It also support client authentication. While this grant type is supported on its own, it is generally recommended you combine that with identity tokens which turns it into the so called hybrid flow. Hybrid flow gives you important extra features like signed protocol responses.

Hybrid¶

Hybrid flow is a combination of the implicit and authorization code flow - it uses combinations of multiple grant types, most typically code id_token. In hybrid flow the identity token is transmitted via the browser channel and contains the signed protocol response along with signatures for other artefacts like the authorization code. This mitigates a number of attacks that apply to the browser channel. After successful validation of the response, the back-channel is used to retrieve the access and refresh token. This is the recommended flow for native applications that want to retrieve access tokens (and possibly refresh tokens as well) and is used for server-side web applications (MVC) and native desktop/mobile applications.

Implicit¶

The implicit grant type is optimized for browser-based applications. Either for user authentication-only (both server-side and JavaScript applications - MVC WebApp), or authentication and access token requests (JavaScript applications - SPA). In the implicit flow, all tokens are transmitted via the browser, and advanced features like refresh tokens are thus not allowed.

The implicit grant type is not recommended due to the inherent risks of returning access tokens in an HTTP redirect without any confirmation that it has been received by the client.

Applications¶

In terms of Authentication configuration we will have to consider that an application has a dual behaviour:

• As an API resource that needs protection
• As a client that requires access to other resources (user identities and API resources)

As described in the above sample, at the highest level, applications A and B are clients and B and C are API resources. Although, B is a client and also an API resource.

Persistence and database¶

All information related to authentication is stored in the security database in the authentication schema, and following the same design provided by IdentityServer.