Authentication Flows

Introduction

The CoreOne Authentication Services uses OpenID Connect as the default protocol. While using this protocol, you are asked to choose one or multiple allowed authentication flows for each of the clients that you are registering. Oftentimes this can be confusing to administrators and developers alike, so this page aims to clarify all the questions you might have.

First of all we need to clarify the naming:

Most common flows

The flows described here are the ones that are typically used by a web application or mobile app. These are the ones that are most widely used. There are more flows available that we will discuss later on.

Authorization Code Flow

The authorization code flow allows you to request an authorization code that will be sent front-channel (the web-browser, Android app,…). From there, the front-channel can send the authorization code to the server-side, where the authorization code can be exchanged for an identity token by calling the authorization endpoint.

This flow does no expose the identity token directly to the front-channel. The only thing exposed to the front-channel is the authorization code. As this is vulnerable to something called authorization code interception, its best-practice to also use PKCE (Proof Key Exchange), which you can simply activate in the client configuration in the CoreOne Admin UI.

Implicit Flow

With the implicit flow, you are sending the identity tokendirectly to the front-channel (the web-browser, Android App,…). That means that the front-channel is in possession of the identity token. For some applications, mostly web-applications, this is convenient as all the data from the token is directly accessible within the browser. But with convenience comes danger, as the identity token is present in the browser. To minimize the risk, the CoreOne Authentication Services requires a nonce by default. But this must be checked by the client library as well.

Hybrid Flow

This flow allows both previous flows to be active at the same time.

Which one should I use?

The general consent here is to use authorization code flow with PKCE wherever possible. In most cases this is possible, but this depends on the used library off the application. Developer usually do not have to implement OpenID Connect themselves. For some languages and frameworks like .NET there is built in support for OIDC and the developer simply has to configure it. For other languages like PHP there is no built-in support and a developer can use one of the many available libraries. So there is a chance that this library is not supporting the authorization code flow with PKCE. If so, you should try to either use a different library or be aware of the risks that are attached to it.

Advanced flows

Besides the three most common flows, there are some other flows available that are mainly used in more advanced setups.

Client credentials

This is the simplest version of all the flows which can be used to secure connections between two server systems. As the name already indicates, there is no user involved in this flow. The token is issued simply by providing a client_id and client_secret to the CoreOne Authentication Services. As long as they match, a token is issued, that does not contain any personal information.

It’s good practice to work with at least on API Resource here. By adding the appropriate api_resource or to be more precise, a scope containing the api_resource to the client configuration in the CoreOne Admin UI. This way you can - like with any other flow as well - indicate the intention of the token. The example below is issued to a test client, and we can clearly see that this client does have access to the cos_app_api and the cos_auth_api as indicated in the scope and the aud.

Resource owner password / password

With a request owner password flow or simply password flow, you can request a token on behalf of the user. With this non-interactive flow, you simply send the username and the password of the user with the authorization request. But as this is a non-interactive flow, the username and password of the user most be gathered somehow, so this is mainly used in legacy applications where a user might enter username and password on the application's login mask rather than on the CoreOne Authentication Services login form. It's best practice to only use this flow as a way of migrating to a more appropriate flow like authorization code, implicit or hybrid flow.

Device flow

This flow is specifically designed for browserless systems or a system with no input device attached, hence the word device. In this flow, the authentication is outsourced to an external device. This is typically used by IoT devices. A good example might be a smart TV where you have to confirm the login process on your mobile device by clicking on a link that has been sent to your email address. There is only limited support within the CoreOne Authentication Services for this flow as of this day.

Delegation flow

Often times there is a situation when a user access one service or endpoint but the actual action is performed on a different service or endpoint. A good example for this is an API Gateway in front of a micro service architecture. A user might call an action on the API Gateway and provide an access token for said API Gateway. The gateway will then simply forward the request to the appropriate microservice. There are various ways to solve this but the recommended solution uses a flow that is not part of the OAuth or OIDC specification but is commonly used: delegation flow.

If you select the delegation flow, the CoreOne will allow the API Gateway to get a token for the microservice on behalf of the user by sending it’s original token - issued for the API Gateway - to the CoreOne Authentication Services in return for an access token for the micro service.