Platform Authorization and Authentication

Primus uses the OAuth2 protocol for the authorization of users. OAuth2 itself does not directly deal with the authentication of users and clients. However, the authentication is required to grant authorization and thus access.

The authentication provides information about “who one is”, for example, the registered Windows user User1. The authorization deals with the information about “who grants which permissions to whom”. For example, the authorization service grants several user rights to the Windows user User1 based on the Windows groups to which Users1 is a member of.

Single Sign-on (SSO) occurs when a user logs in to one application and is then signed in to other applications automatically, regardless of the platform, technology, or domain the user is using. The user signs in only one time, hence the name of the feature (Single Sign-on). To achieve single sign-on (SSO) for Primus and all its components and external clients, the platform now uses OpenID Connect (OIDC). OIDC is an open authentication protocol that profiles and extends OAuth 2.0 to add an identity layer. OIDC allows clients to confirm an end user's identity using authentication by an authorization server.

For example, a user (resource owner) provides its credentials to the client, in this case the STG.RT.API, to obtain an access token from the authorization server. The access token can then be used to obtain protected resources from a resource server such as the Primus configuration service.

Note that for the sample above there are three major communication paths that are not shown in the simplifying schematic, however, the Primus uses them:

• The Authorization Server does not show the authentication service
• The Resource Server generally verifies the access token with the authorization server for validity.

In general, the access token provided by the TCG Authorization Server is accompanied with a long-lived refresh token. Once the access token expires, the refresh token is used to obtain a new access and refresh token. Each refresh token can only be used once. Refresh tokens are only intended for the client and are not intended to be passed on to a resource service. Refresh tokens provide a further layer of security as a potential attacker can only misuse an intercepted access token for a short period of time. An access token by itself cannot be exchanged for a new access token.

Primus provides authentication via different methods:

• Authorization Code Flow with PKCE via a web browser

• User name and password authentication via the password grant flow

• Client authentication via the client credentials grant flow

Authorization Code Flow with PKCE

This authorization flow is the current best practice when logging into any client application because it avoids entrusting a client application with user credentials.

The Authorization Code Flow with PKCE (proof key for code exchange) is a security extension for public clients like web sites. A user that wants to log into a web site is redirected to the log in page of the TCG Authorization Server. If the user has not yet authenticated itself to the TCG Authorization Server, he enters a user name or password into the login field. After the credentials have been verified, the user is redirected back to the web site where he started, along with a authorization code. This authorization code is used by the website to exchange it with the Authorization Server for an access token. The authorization code part prevents user credentials to ever be entered into a potentially non-trusted client application. The PKCE part in this flow prevents the access tokens to be passed around in redirect URLs shown in the browsers URL tab, thereby preventing accidental token leakage by copy/pasting the url.

Any other website or WPF application that uses the TCG Authorization Server as its authorization authority can from that point onwards be used without having to provide the username or password again, as long as the user is still authenticated to the TCG Authorization Server via his web browser. When the user moves to a different computer or uses a different browser, he has to repeat the login flow.

Authorization via User Name and Password

For the password grant flow type of the authentication, the platform sends a user name and password to the authorization service that then uses an internal authentication provider to confirm the correctness of both. Upon a correct user name and password, the authorization service creates an access token and request token with the claims of the user from the Windows groups the user is a member of.

Authorization via client credentials

The client credentials grant flow type of authorization allows you to register client credentials with the authorization service, along with claims which each clientId may receive. This type of authorization is intended for machine-to-machine communication and not for typical user interactions. In this flow, a client Id and matching client secret is sent to the authorization service that issues an access token. Once the access token expires, client Id and client secret can be used again to obtain a new access token. Also, in some cases a refresh token is made available that can also be used to acquire a new access token.

Since the client credentials flow uses a client ID and secret, the administrator must make sure that these client credentials are stored in a secure manner and can only be accessed by authorized users. On Windows, they are usually stored in files where only authorized users as well as the service using these credentials has access. An additional layer of security can be added by encrypting the client secret and only giving authorized users as well as the service access to the encryption keys. The additonal layer does not prevent administrators to extract the secrets from machines, but it prevents leaking the secret by accidentally copying and distributing the file containing the secret.

Refresh Token Flow

The authorization service provides an access token together with a long-lived refresh token, if the used client ID has the permission to use refresh tokens and uses the scope 'offline_access'. Once the access token expires, the refresh token is used to obtain a new access and refresh token. Each refresh token can only be used once. Refresh tokens are only intended for the client and are never intended to be passed on to a resource service.

Refresh tokens provide a further layer of security as a potential attacker can only misuse an intercepted access token for a short period of time. An access token by itself cannot be exchanged for a new access token.