User authentication¶
Authentication of users in Vidispine can be performed in a number of ways depending on the requirements of the calling application.
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.
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.
Creating a time-limited token using the API with one of the options above, see Get an authentication token for a user. This token can then be used in subsequent calls as credential by specifying the http header:
Authorization: token {token}
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:
- Have the user log in by providing user name and password.
- Authenticate the user with
/user/{user-name}/validate
. - Store the user name with the session.
- Use the
RunAs
header with all communication to the Vidispine API.
Apache Shiro Integration¶
New in version 4.1.
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 commandline shiro.ini will be
loaded from the current directory.
The default configuration file that can be used as a template can be seen below.
Note
The token authentication filter and the Vidispine realm must always be kept so that requests performed internally by Vidispine will still function.
[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¶
- 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/
. - Create a
shiro.ini
file based on the above template and modify it to your needs. - 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.
[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:
GET /API/version HTTP/1.1
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
User-Agent: curl/7.32.0
Host: localhost:8080
Accept: */*
HTTP/1.1 200 OK
...
GET /API/version HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
User-Agent: curl/7.32.0
Host: localhost:8080
Accept: */*
HTTP/1.1 200 OK
...
GET /API/version HTTP/1.1
Authorization: Basic YWRtaW46aW52YWxpZA==
User-Agent: curl/7.32.0
Host: localhost:8080
Accept: */*
HTTP/1.1 401 Unauthorized
...
Note
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¶
New in version 4.13.1.
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:
[main]
...
$userInfoProvider = com.example.CustomRealmUserInfoProvider
userCreationListener = com.vidispine.security.auth.UserCreationListener
userCreationListener.infoProvider = $userInfoProvider
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.
OAuth 2.0¶
New in version 4.4.
Version 4.4 contains a Shiro filter that can be used to authenticate Bearer
tokens.
To use, add the following to shiro.ini:
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
...
[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic
The validation of tokens can be done in three ways:
- By checking the token against a static public key in an X.509 certificate.
- By checking the token against public keys given by federation metadata.
- By checking the token against a validation provider.
Example: static public key¶
To set a static public key, add the following to shiro.ini:
[main]
...
oauth2Auth = com.vidispine.security.auth.BearerAuthenticationFilter
oauth2Auth.x509Certificate = {x509-certificate}
oauth2Auth.expectedAudience = {expected-audience}
oauth2Auth.tokenUser = email # example
...
[urls]
/** = noSessionCreation, tokenAuth[permissive], oauth2Auth[permissive], authcBasic
Where {x509-certificate}
is an X.509 certificate encoded with Base64, e.g. MII...==
.
Token validation includes these steps:
- Vidispine uses the certificate from
{x509-certificate}
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.
[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.
[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.