Authentication Service [GL ARC]

Motivation

Authentication Service is the central component for authentication and authorization of an Enterprise MAM Solution:

All frontends authenticate via Authentication Service.
Backend applications accessing authenticated endpoints of an Enterprise MAM Solution authenticate via Authentication Service.
Backend applications providing authenticated API endpoints accept and validate tokens via Authentication Service.

OpenID Connect

Authentication Service is based on the OpenID Connect standards. This not only brings with it a high security level, it also easy access to all authenticated APIs as there are ready-made client libraries available for almost any programming language or framework.

User & Group Management

Authentication Service always uses and external identity provider for obtaining users and groups. Only the built-in admin account and functional accounts for backend services are managed directly by Authentication Service. All further accounts, in particular accounts for human users, must be managed via the identity provider.

This allows implementers to benefit from crucial security mechanisms provided by the identity provider and share all relevant configuration (password complexity rules, password expiry rules, account expiry, account blocking, and many more) with an Enterprise MAM Solution.

Authentication Service In Kubernetes

Authentication Flows for Frontend Applications

Implicit Flow

User-centric web-based front-ends of an Enterprise MAM Solution use the OIDC implicit flow to authenticate:

Authorization Code Flow

EditMate and some administrative user interfaces use the authorization code flow:

Client Credentials Flow

Backend applications use the OIDC client credentials flow to obtain a token for accessing other backend services:

User And Group Syncing

This diagram shows how users & groups are fetched from the configured identity provider and where they are stored:

Endpoints

AuthService currently exposes the following endpoints for authentication purposes:

Endpoint	Description
Discovery Endpoint	The discovery endpoint can be used to retrieve metadata about your IdentityServer - it returns information like the issuer name, key material, supported scopes etc. Example CODE `http://vidiflow.colosseum.azure.arvato-systems-media.net/vpms3/authservice/.well-known/openid-configuration`
Authorize Endpoint	The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.
Token Endpoint	The token endpoint can be used to programmatically request tokens. It supports the `password`, `authorization_code`, `client_credentials`, `refresh_token` and `urn:ietf:params:oauth:grant-type:device_code` grant types. Furthermore the token endpoint can also be extended to support other extension grant types.
Userinfo Endpoint	The userInfo endpoint can be used to retrieve identity information about a user. The caller needs to send a valid access token representing the user. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims (at least the openid scope is required).
End Session Endpoint	The end session endpoint can be used to trigger single sign-out. To use the end session endpoint a client application will redirect the user’s browser to the end session URL. All applications that the user has logged into via the browser during the user’s session can participate in the sign-out.
Check Session Endpoint	After signing in a user with OpenID Connect the client application may need to periodically check if the user is still logged in with the OpenID provider. Core OpenID Connect enables clients to silently check for that, by repeating the original OpenID authentication request with the optional `prompt=none` parameter appended to it. This instructs the server to return a new ID token without any user interaction, unless the user is no longer authenticated or client access was revoked (signalled by a login_required, consent_required or the catch-all interaction_required error).
Revocation Endpoint	The revocation endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification (RFC 7009).
Introspection Endpoint	The introspection endpoint is an implementation of RFC 7662. It can be used to validate reference tokens (or JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries). The introspection endpoint requires authentication - since the client of an introspection endpoint is an API, you configure the secret on the `ApiResource`.
Device Authorization Endpoint	The device authorization endpoint can be used to request device and user codes. This endpoint is used to start the device flow authorization process.

Tokens

Since AuthService is OIDC compliant, it issues and manages the following tokens for various purposes as described below:

Tokens

Description

Identity Token

The ID Token, which also known as Identity Token, Security Tokens, Authentication Tokens or even Software Tokens, is a security token that contains claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims. The ID Token is represented as a JSON Web Token (JWT). This means that:

identity information about the user is encoded right into the token and
the token can be definitively verified to prove that it hasn’t been tampered with.

ID Tokens MUST be signed using JWS and optionally both signed and then encrypted using JWS and JWE respectively on the OpenId Provider (OP), thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality.

Example

JSON

{
  "nbf": 1626232241,
  "exp": 1626243041,
  "iss": "https://vidiflow.colosseum.azure.arvato-systems-media.net/vpms3/authservice",
  "aud": [
    "identityscope",
    "https://vidiflow.colosseum.azure.arvato-systems-media.net/vpms3/authservice/resources"
  ],
  "jti": "DA986AA663BE2559A548A9752D268F5A",
  "sid": "5FD058EFA7ECC9F713356AA0616D6F43",
  "iat": 1626232241
  "client_id": "authServiceClient",
  "sub": "7b38b7f2-b100-4167-b884-006caa62dd64",
  "auth_time": 1626232241,
  "idp": "local",
  "vidispine_user": "alice",
  "display_name": "Alice",
  "AspNet.Identity.SecurityStamp": "TZZDHXEK6KX4NB63GIAOALNIKNJ7G3E7",
  "role": [
    "PF_MetadataEditor",
    "PF_MetadataUser",
    "EM_USER",
    "CP_VIEWER"
  ],
  "preferred_username": "alice",
  "name": "alice"
}

Access Token

An access token is a credential that can be used by an application to access an API. Access Tokens can be either an opaque string or a JSON web token. They inform the API that the bearer of the token has been authorized to access the API and perform specific actions specified by the scope that has been granted.

Access Tokens should be used as a Bearer credential and transmitted in an HTTP AuthorizationHeader to the API. A bearer token means that the bearer can access authorized resources without further identification.

Example

JSON

{
  "nbf": 1626232241,
  "exp": 1626243041,
  "iss": "https://vidiflow.colosseum.azure.arvato-systems-media.net/vpms3/authservice",
  "aud": [
    "identityscope",
    "https://vidiflow.colosseum.azure.arvato-systems-media.net/vpms3/authservice/resources"
  ],
  "client_id": "authServiceClient",
  "sub": "7b38b7f2-b100-4167-b884-006caa62dd64",
  "auth_time": 1626232241,
  "idp": "local",
  "jti": "DA986AA663BE2559A548A9752D268F5A",
  "sid": "5FD058EFA7ECC9F713356AA0616D6F43",
  "iat": 1626232241,
  "scope": [
    "identityscope"
  ],
  "amr": [
    "pwd"
  ]
}

Refresh Token

Since access tokens have finite lifetimes, refresh tokens allow requesting new access tokens without user interaction.

Refresh tokens are supported for the following flows: authorization code, hybrid and resource owner password credential flow. The clients needs to be explicitly authorized to request refresh tokens by setting AllowOfflineAccess to true.

There are currently 2 lifetime settings for the Refresh Token

AbsoluteRefreshTokenLifetime
Maximum lifetime of a refresh token in seconds. Defaults to 2592000 seconds / 30 days. Zero allows refresh tokens that, when used with RefreshTokenExpiration = Sliding only expire after the SlidingRefreshTokenLifetime is passed.
SlidingRefreshTokenLifetime
Sliding lifetime of a refresh token in seconds. Defaults to 1296000 seconds / 15 days

Examples

The following examples indicates how Vidispine applications interact with the AuthService to obtain and use its token for validating and accessing the APIs using the OpenConnectId.

Authenticating The VidiCore API

JWT token validation is done in VidiCore via the public key of the certificate used by Authentication Service for signing JWT tokens. The public key of the signing certificate is exposed by Authentication Service on the OpenIDConnect discovery endpoint. During startup of the VidiCore Kubernetes pod, an init container is obtaining the signing certificate from the discovery endpoint and stores it as x509Certificate in VidiCore via the OAuth2 configuration API. This init container also configures the expectedAudience and tokenUser attributes appropriately.

When VidiCore is receiving a JWT token, it:

verifies the token’s signatures against the public key of the signing certificate;
checks if the aud claim in the JWT token (see example below) matches the expectedAudience value configured by the init container;
checks if the token has not expired yet by reading the exp value (Unix timestamp) and verifying that is still is in the future;
check if the token has a sub claim - it only has to be present, the actual value has no meaning;
obtains the VidiCore user name from the claim configured as tokenUser by the init container - tokenUser contains the fixed value vidispine_user in all Enterprise MAM installations.

From that point on VidiCore knows the name of the user doing the API call and treats this user as an authenticated user. VidiCore roles (functional rights) and ACLs (asset access rights) are applied to the API call for this user in the same way as for basic authentication.

Example Token

CODE

{
  "nbf": 1612446231,
  "exp": 1612457031,
  "iss": "http://colosseumeuk8s.westeurope.cloudapp.azure.com/vpms3/authservice",
  "aud": [
    "configportalscope",
    "identityscope",
    "http://colosseumeuk8s.westeurope.cloudapp.azure.com/vpms3/authservice/resources"
  ],
  "client_id": "configportalclient",
  "client_role": "CP_API_ADMIN",
  "sub": "8b38b7f2-b956-4165-b284-006caa62dd64",
  "auth_time": 1612446231,
  "idp": "local",
  "ntlm_username": "admin",
  "vidispine_user": "admin",
  "display_name": "admin",
  "email": "",
  "phone_number": "",
  "role": [
    "EM_USER",
    "PF_WfExpert",
    "EM_Test_Super_User",
    "MP_Admin",
    "PF_WfUser",
    "PF_MetadataEditor",
    "CP_VIEWER",
    "PF_WfArvato",
    "PF_MetadataUser",
    "MP_API_CONSUMER",
    "MP_Collection-Full-Access",
    "MP_Collection-Rename",
    "PF_WfEditor",
    "MP_Basic-User",
    "CP_EDITOR",
    "CP_ARVATO",
    "CP_EXPERT"
  ],
  "AspNet.Identity.SecurityStamp": "d82e6d74-fe57-4fe6-85c1-6768ba3eb53b",
  "preferred_username": "admin",
  "name": "admin",
  "sid": "AC7EED8B8E07FA02D4A7EC54BD381A54",
  "iat": 1612446231,
  "scope": [
    "openid",
    "profile",
    "configportalscope",
    "identityscope"
  ],
  "amr": [
    "pwd"
  ]
}

Authenticating VidiFlow APIs

VidiFlow’s APIs follow the same basic principles as described above for VidiCore:

Fetch the public key for token signing from the OIDC discovery document once during startup of the service.
Validate the received token signature against the public key.
Extract expiry time from token and check if it’s still valid.
Check for the appropriate OIDC client and scopes.
Extract roles from token and check if supplies roles match required roles for this API call.