Skip to main content
Skip table of contents

User authentication [VC 21.3 GEN]

Authentication of users in Vidispine can be performed in a number of ways depending on the requirements of the calling application.

  1. By passing the user credentials to Vidispine on each request and letting Vidispine authenticate the user based on the credentials stored in the Vidispine database.

    The default HTTP authentication method is HTTP basic authentication. To use a custom HTTP authentication method, have a look at Apache Shiro Integration.

  2. Using Run-As: The application can itself authenticate the user and then connect to Vidispine using a service account with the Run-As privilege and with the Run-As option enabled, so that the request is then performed as the already authenticated user.

  3. Creating a time-limited token using the API with one of the options above, see Retrieve an authentication token. This token can then be used in subsequent calls as credential by specifying the HTTP header:

    PYTHON 
    Authorization: token {token}

  4. Using long-lived access keys. Access keys are used with HTTP basic authentication, just like with normal username and password credentials.

Run-As option

The API supports the operation of having the calling application authenticate itself via a single password or a single certificate credential. The actual end-user can then be specified by the RunAs HTTP header. The calling application credential must have _administrator or _runas role. The actual end-user roles will be determined by the RunAs user’s credentials.

A typical UI application scenario would be:

  1. Have the user log in by providing user name and password.

  2. Authenticate the user with PUT /user/(username)/validate.

  3. Store the user name with the session.

  4. Use the RunAs header with all communication to the Vidispine API.

Token authentication

The above scenario can also be achieved using short-lived authentication tokens.

  1. Have the user log in by providing user name and password.

  2. Request an authentication token using GET /token or GET /user/(username)/token.

  3. Store the authentication token with the session.

  4. Use the token to authenticate all communication to the Vidispine API.

The GET /token endpoint can be used when using access keys to authenticate, in case the username of the user is unknown.

Use access keys

Access keys can be seen as longed-lived authentication tokens, except that they do not expire. Multiple access keys can be created for a single user, and can be disabled so that they no longer can be used to successfully authenticate as that user. Deleting an access key will permanently disable it.

The only time the access key secret will be available is when the access key is first created.

To create an access key:

NONE 
POST /user/stephen/key/
Accept: application/xml
HTML/XML 
<AccessKeyDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VSIDEWKIL4R27GPSJ562</id>
  <secret>pWUlPFHqyJom2Wq+XaGIUVRQqgx5jgnaLIY37/DT</secret>
  <status>ACTIVE</status>
  <created>2018-06-01T10:36:13.891+02:00</created>
</AccessKeyDocument>

The access key id and secret can the be used to authenticate further requests:

NONE 
GET /whoami
Authorization: Basic VlNJREVXS0lMNFIyN0dQU0o1NjI6cFdVbFBGSHF5Sm9tMldxK1hhR0lVVlJRcWd4NWpnbmFMSVkzNy9EVA==
NONE 
200 OK

stephen

Apache Shiro Integration

As of Vidispine 4.1 requests can be forwarded to Apache Shiro for authentication, making it is possible to customize how existing users in Vidispine are authenticated. The Apache Shiro version that is bundled with Vidispine can be seen in the table below.

Vidispine version

Apache Shiro version

4.12

1.4.0

4.1

1.2.2

Custom configuration

On startup Vidispine will try to read a Apache Shiro INI configuration file from $instanceRoot/[config/]shiro.ini. The instance root folder typically is /var/lib/vidispine/server. In case you are starting Vidispine manually via command line shiro.ini will be loaded from the current directory.

The default configuration file that can be used as a template can be seen below.

The token authentication filter and the Vidispine realm must always be kept so that requests performed internally by Vidispine will still function.

NONE 
[main]
vidispineRealm = com.vidispine.security.auth.DefaultVidispineRealm
tokenAuth = com.vidispine.security.auth.TokenAuthenticationFilter
deny = com.vidispine.security.auth.DenyFilter

securityManager.realms = $vidispineRealm
authcBasic.applicationName = vidispineRealm

[urls]
/** = noSessionCreation, tokenAuth[permissive], authcBasic

Installing a custom filter or realm

  1. Make the JAR file containing your custom filter or realm available on the classpath. With the vidispine-server package, the JAR file should be copied to /usr/share/vidispine/server/lib/ext/.

  2. Create a shiro.ini file based on the above template and modify it to your needs.

  3. Start/Restart the Vidispine service.

Example: Static credentials

This is an example showing how to add a custom realm, in this case a IniRealm that defines credentials for a static set of users directly in the configuration file.

NONE 
[main]
vidispineRealm = com.vidispine.security.auth.DefaultVidispineRealm
tokenAuth = com.vidispine.security.auth.TokenAuthenticationFilter
deny = com.vidispine.security.auth.DenyFilter

securityManager.realms = $iniRealm, $vidispineRealm
authcBasic.applicationName = "vidispineRealm"

[urls]
/** = noSessionCreation, tokenAuth[permissive], authcBasic

[users]
admin=password

Testing the configuration:

NONE 
GET /API/version HTTP/1.1
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
User-Agent: curl/7.32.0
Host: localhost:8080
Accept: */*

HTTP/1.1 200 OK
...
NONE 
GET /API/version HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
User-Agent: curl/7.32.0
Host: localhost:8080
Accept: */*

HTTP/1.1 200 OK
...
NONE 
GET /API/version HTTP/1.1
Authorization: Basic YWRtaW46aW52YWxpZA==
User-Agent: curl/7.32.0
Host: localhost:8080
Accept: */*

HTTP/1.1 401 Unauthorized
...

By default Apache Shiro will accept a request if at least one realm accepts the provided credentials, which is why the passwords password (accepted by iniRealm and admin (accepted by vidispineRealm) are both accepted.

Automatic creation of users

When using a custom Shiro realm to authenticate users, it may be the case that the user exists in the custom realm, but not in Vidispine. The Shiro authentication listener com.vidispine.security.auth.UserCreationListener, can be used to have users automatically created/updated after a successful authentication attempt, to match the user information provided by that realm.

In the shiro.ini, add the user creation listener:

NONE 
[main]
...
userInfoProvider = com.example.CustomRealmUserInfoProvider
userCreationListener = com.vidispine.security.auth.UserCreationListener
userCreationListener.infoProvider = $userInfoProvider
userCreationListener.enableUserOnLogin = true
securityManager.authenticator.authenticationListeners = $userCreationListener

The com.vidispine.security.auth.UserCreationListener requires a com.vidispine.security.auth.spi.VidispineUserInfoProvider that can return the Vidispine user information from the user account information from Shiro/the custom realm.

The implementation of the VidispineUserInfoProvider, com.example.CustomRealmUserInfoProvider in the example above, should be placed in a JAR file available on the classpath, typically in the /usr/share/vidispine/server/lib/ext/ directory.

Changed in version 4.17.4: The enableUserOnLogin field was added.

OAuth2 and automatic user creation doesn’t work together at the moment.

OAuth 2.0

Version 4.4 contains a Shiro filter that can be used to authenticate Bearer tokens. To use, add the following to shiro.ini:

NONE 
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
...

[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic

The validation of tokens can be done in three ways:

  1. By checking the token against a plain public key or a public key in an X.509 certificate.

  2. By checking the token against public keys given by federation metadata.

  3. By checking the token against a validation provider.

Example: static public key(s)

To set the static public key(s), add the following to shiro.ini:

NONE 
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
oauth2Auth.x509Certificate = {x509-certificateA}, {x509-certificateB}
oauth2Auth.publicKey = {publicKeyA}, {publicKeyB}
oauth2Auth.expectedAudience = {expected-audience}
oauth2Auth.tokenUser = email  # example
...

[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic

Where {x509-certificate} is a X.509 certificate encoded with Base64, e.g. MII...== and, similarly, the {publicKey} is a Base64 encoded public key, e.g MII...AB. Token validation includes these steps:

  • Vidispine circles through the certificates and public keys provided, e.g {x509-certificateA}, {x509-certificateB}`, ``{publicKeyA}, {publicKeyB} and tries to verify the token’s signature.

  • The JWT claim sub must be present in the token (it’s value isn’t used).

  • The JWT claim aud must contain an entry matching the {expected-audience} value.

After successful token validation Vidispine reads the JWT claim defined by the tokenUser property and uses it as Vidispine user name.

Example: federation metadata

Federation metadata is similar to a static certificate, but multiple certificates can be used, and they are automatically downloaded regularly.

NONE 
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
oauth2Auth.federationMetadataURI = https://login.microsoftonline.com/common/FederationMetadata/2007-06/FederationMetadata.xml
oauth2Auth.federationMetadataInterval = 86400
oauth2Auth.expectedAudience = https://graph.windows.net
oauth2Auth.tokenUser = unique_name
...

[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic

Example: validation service

Here, The token is validated against validation server. The result is stored in cache for 10 minutes.

NONE 
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
oauth2Auth.validationEndpoint = https://www.googleapis.com/userinfo/v2/me
oauth2Auth.tokenUser = email
...

[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic

In an OpenID Connect (OIDC) context token validation usually will take place against the OIDC userinfo endpoint. Depending on your OIDC server this may require tokens with the oidc scope that are available in the OIDC hybrid flow.

In the example above with Google, the https://www.googleapis.com/auth/userinfo.email scope is used.

Configure OAuth2 using the API

New in version 4.17.

You can update the OAuth2 configuration via the API. To enable/disable the API access, from the shiro.ini file, use the setting: allowConfigUpdate true/false. If there is no shiro.ini file present, the API access is enabled by default. Only users with the _administrator role can access the configuration from the API.

Example

NONE 
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
oauth2Auth.x509Certificate = {x509-certificate}
oauth2Auth.expectedAudience = {expected-audience}
oauth2Auth.tokenUser = sub
oauth2Auth.allowConfigUpdate = false
...

[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic

Example

Get the current configuration.

NONE 
GET /configuration/auth
Content-Type: application/xml

<OAuth2ConfigurationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <federationMetadataInterval>86400</federationMetadataInterval>
    <tokenUser>unique_name</tokenUser>
</OAuth2ConfigurationDocument>

Example

Updating the configuration for a X.509 certificate.

NONE 
PUT /configuration/auth
Content-Type: application/xml

<OAuth2ConfigurationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <x509Certificate>{x509certificate}</x509Certificate>
    <expectedAudience>{expected-audience}</expectedAudience>
    <tokenUser>email</tokenUser>
</OAuth2ConfigurationDocument>

Example

Changed in version 5.6.

Updating the configuration for multiple X.509 certificates and public keys.

NONE 
PUT /configuration/auth
Content-Type: application/xml

<OAuth2ConfigurationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <x509Certificate>{x509certificateA}</x509Certificate>
    <x509Certificate>{x509certificateB}</x509Certificate>
    <publicKey>{public-keyA}</publicKey>
    <publicKey>{public-keyB}</publicKey>
    <expectedAudience>{expected-audience}</expectedAudience>
    <tokenUser>sub</tokenUser>
</OAuth2ConfigurationDocument>

Example

Updating the configuration for federation metadata.

NONE 
PUT /configuration/auth
Content-Type: application/xml

<OAuth2ConfigurationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <federationMetadataURI>https://login.microsoftonline.com/common/FederationMetadata/2007-06/FederationMetadata.xml</federationMetadataURI>
    <federationMetadataInterval>86400</federationMetadataInterval>
    <expectedAudience>https://graph.windows.net</expectedAudience>
    <tokenUser>unique_name</tokenUser>
</OAuth2ConfigurationDocument>

Example

Updating the configuration for validation service.

NONE 
PUT /configuration/auth
Content-Type: application/xml

<OAuth2ConfigurationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <validationEndpoint>https://www.googleapis.com/userinfo/v2/me</validationEndpoint>
    <tokenUser>email</tokenUser>
</OAuth2ConfigurationDocument>

Example

Delete the current configuration.

NONE 
DELETE /configuration/auth
Content-Type: application/xml
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close