Applications

AuthService provides APIs that allow admins to securely register and configure their client applications that requires API access authentication and authorization.

Integration

To integrate any client application with AuthService as the Identity Provider for the application, the following steps must be taken:

  1. The client application must define all of its public/scoped/internal APIs that would need to be managed by AuthService, and register those resources via AuthService Resource Configuration. The actual implementations of those scoped rights and permissions for the registered resources are within the responsibility of the client application.

  2. The client application would need to configure the Client Configuration and do a POST operation to register that application to be managed by AuthService. Use the PUT operation instead to update existing clients.

  3. The client application would then need to implement supports for OpenID Connect (OIDC) and OAuth2 protocol for the client-side applications. There are some well-known third-party client side library support for such purposes (with examples) as follows:

  4. For authorization and authentication to happen, the client application would be expected to always send an authorization request either of the following endpoints:

Configurations

Client Configuration

The /Client API allows admins to register all client applications to be managed by the AuthService for authentication and authorization purposes.

The configuration properties for /Client are as follows:

Item

Description

clientId

Unique ID of the client.

Example

configportalclient
CODE

clientName

Client display name (used for logging and consent screen).

Example

ConfigPortal UI
CODE

clientUri

URI to further information about client (used on consent screen).

Example

http://www.example.com/ConfigPortal/WebUI/
CODE

logoUri

URI to client logo (used on consent screen).

Example

http://www.example.com/ConfigPortal/WebUI/logo.png
CODE

enabled

Specifies if client is enabled (Default: true).

Example

true
CODE

protocolType

Gets or sets the protocol type. (Default: oidc)

Example

oidc
JSON

description

Description of the client application.

Example

This is the config portal web ui application. 
CODE

pairWiseSubjectSalt

Gets or sets a salt value used in pair-wise subjectId generation for users of this client.

userCodeType

Gets or sets the type of the device flow user code (Default: ““). See examples here.

identityTokenLifetime

Lifetime of identity token in seconds (Default: 300 seconds / 5 minutes).

Example

300
CODE

accessTokenLifetime

Lifetime of access token in seconds (Default: 3600 seconds / 1 hour).

Example

3600
CODE

authorizationCodeLifetime

Lifetime of authorization code in seconds (Default: 300 seconds / 5 minutes).

Example

300
CODE

absoluteRefreshTokenLifetime

Maximum lifetime of a refresh token in seconds. (Default: 2592000 seconds / 30 days).

Example

2592000
CODE

slidingRefreshTokenLifetime

Sliding lifetime of a refresh token in seconds. (Default: 1296000 seconds / 15 days).

Example

1296000
JSON

consentLifetime

Lifetime of a user consent in seconds. (Default: null (no expiration))

Example

300
JSON

userSsoLifetime

The maximum duration (in seconds) since the last time the user authenticated. (Default: null (no expiration))

Example

300
JSON

deviceCodeLifetime

Gets or sets the device code lifetime (Default: 300).

Example

300
CODE

refreshTokenUsage

Determines whether the Refresh Token should be reused. (Default: 1)

  • 0 - Re-use. The refresh token handle will stay the same when refreshing tokens

  • 1 - One time only. The refresh token handle will be updated when refreshing tokens

updateAccessTokenClaimsOnRefresh

Gets or sets a value indicating whether the access token (and its claims) should be updated on a refresh token request. (Default: false)

Example

false
JSON

refreshTokenExpiration

Determines the type of Refresh Token. (Default: 1)

  • 0 - Sliding. When refreshing the token, the lifetime of the refresh token will be renewed (by the amount specified in slidingRefreshTokenLifetime). The lifetime will not exceed absoluteRefreshTokenLifetime.

  • 1 - Absolute. The refresh token will expire on a fixed point in time (specified by the absoluteRefreshTokenLifetime)

accessTokenType

Specifies whether the access token is a self contained JWT token or reference token (Default: 0).

  • 0 - Jwt. A JWT token would be a self-contained access token - it’s a protected data structure with claims and an expiration. Once an API has learned about the key material, it can validate self-contained tokens without needing to communicate with the issuer. This makes JWTs hard to revoke. They will stay valid until they expire.

  • 1 - Reference. It will store the contents of the token in a data store and will only issue a unique identifier for this token back to the client. The API receiving this reference must then open a back-channel communication to AuthService to validate the token.

enableLocalLogin

Gets or sets a value indicating whether the local login is allowed for this client. (Default: true).

Example

true
JSON

includeJwtId

Gets or sets a value indicating whether JWT access tokens should include an identifier. (Default: true).

Example

true
JSON

requireClientSecret

If set to false, no client secret is needed to request tokens at the token endpoint. (Default: true).

Example

true
JSON

requireConsent

Specifies whether a consent screen is required. (Default: false).

For an enterprise MAM application, this should be always set to false, and the user information that are required to be collected must be specified instead in the documentation.

Example

false
JSON

allowRememberConsent

Specifies whether user can choose to store consent decisions. (Default: true).

Example

true
JSON

requirePkce

Specifies whether a proof key is required for authorization code based token requests. (Default: true).

Example

true
JSON

allowPlainTextPkce

Specifies whether a proof key can be sent using plain method. (not recommended and defaults to false).

Example

false
JSON

requireRequestObject

Specifies whether the client must use a request object on authorize requests. (Default: false).

Example

false
JSON

allowAccessTokensViaBrowser

Controls whether access tokens are transmitted via the browser for this client. (Default: false).

This can prevent accidental leakage of access tokens when multiple response types are allowed.

Example

false
JSON

alwaysSendClientClaims

Gets or sets a value indicating whether client claims should be always included in the access tokens - or only for client credentials flow. (Default: false).

Example

false
JSON

clientClaimsPrefix

Gets or sets a value to prefix it on client claim types. (Default: “”).

It can accept any non empty string if claims should be prefixed with the value; otherwise, null, where the client will not use any prefixes at all in its claims.

Example

client_
CODE

alwaysIncludeUserClaimsInIdToken

When requesting both an id token and access token, should the user claims always be added to the id token instead of requiring the client to use the userInfo endpoint. (Default: false).

This needs to be true for clients in client credentials flow and false for clients in UI-centric flows (e.g. implicit, authorization code).

Example

false
JSON

allowOfflineAccess

Gets or sets a value indicating whether to allow offline access. (Default: false).

Example

false
CODE

frontChannelLogoutUri

Specifies logout URI at client for HTTP front-channel based logout.

Example

https://www.example.com/ConfigPortal/WebUI/logout
JSON

frontChannelLogoutSessionRequired

Specifies is the user's session id should be sent to the frontChannelLogoutUri. (Default: true).

Example

true
JSON

backChannelLogoutUri

Specifies logout URI at client for HTTP back-channel based logout.

Example

https://www.example.com/ConfigPortal/WebUI/logout
JSON

backChannelLogoutSessionRequired

Specifies is the user's session id should be sent to the backChannelLogoutUri. (Default: true).

Example

true
JSON

clientSecrets

Set a collection of secret keys for flows that require secrets to authenticate against.

Example

{
  "description": "Secret key for ConfigPortal Web API",
  "value": "someSecrets",
  "expiration": "2021-07-26T06:44:06.740Z",
  "type": "string"
}
JSON

redirectUris

Specifies allowed URIs to return tokens or authorization codes to.

Example

[
  https://example.com/ConfigPortal/UI/swagger/oauth2-redirect.html
]
JSON

postLogoutRedirectUris

Specifies allowed URIs to redirect to after logout. See the OIDC Connect Session Management spec for more details.

Example

[
  "https://example.com/ConfigPortal/UI/#/"
]
JSON

allowedCorsOrigins

Gets or sets the allowed CORS origins for client applications.

Example

[
  "https://example.com"
]
JSON

allowedGrantTypes

Specifies the allowed grant types. The following combination of values are allowed:

Example

A client must either use an UI-centric flow (e.g. implicit, authorization code) or a backend flow (client credentials) but never both.

[
  "implicit"
]
JSON

allowedScopes

Specifies the API scopes that the client is allowed to request. If empty, the client can't access any scope.

Example

[
  "configportalscope",
  "profile",
  "identityscope",
  "openid"
]
JSON

allowedIdentityTokenSigningAlgorithms

Signing algorithm for identity token. If empty, will use the server default signing algorithm. (Default: [])

Example

[
  "RS256"
]
JSON

identityProviderRestrictions

Specifies which external Identity Providers (IdPs) can be used with this client (if list is empty all IdPs are allowed). (Default: "").

Example

[
  "Facebook"
]
JSON

claims

Allows settings claims for this client (will be included in the access token).

Example

[
  {
    "type": "name",
    "value": "Alice",
    "valueType": "http://www.w3.org/2001/XMLSchema#string"
  }
]
JSON

properties

Gets or sets the custom properties for the client. (Default: {})

Example

{
  "keyString":"valueString"
}
JSON

Resource Configuration

Each client application is expected to expose their own services via some sort of public accessible APIs. Normally, these are known as resources and can be managed by the AuthService to control their accessibility.

API Resource

The API resource here are the type of services where each client application public exposes as APIs. Usually, there will be at least one of them for each client application defined.

The API resource has the following configurations:

Item

Description

name

The unique name of the API resource.

Example

configPortalApi
CODE

displayName

Display name of the API resource.

Example

Config Portal API
CODE

enabled

Indicates if this resource is enabled. (Default: true).

Example

true
CODE

description

Description of the resource.

Example

Access to ConfigPortal API
CODE

showInDiscoveryDocument

Specifies whether this scope is shown in the discovery document. (Default: true).

Example

true
CODE

apiSecrets

The API secret is used for the introspection endpoint. The API can authenticate with introspection using the API name and secret.

Example

[
  {
    "description": "Config Portal API Secret",
    "value": "someSecrets",
    "expiration": "2021-07-27T05:26:20.843Z",
    "type": "string"
  }
]
JSON

scopes

Models the scopes this API resource allows. These are defined and managed by the client application to control the accessibility that the user has.

Example

v1 (Deprecated - please use v2)

[
  {
    "name": "configportalscope",
    "displayName": "Access to ConfigPortal API",
    "enabled": true,
    "description": "",
    "showInDiscoveryDocument": true,
    "required": false,
    "emphasize": false,
    "userClaims": [],
    "properties": {}
  }
]
JSON

v2 (References the ApiScope name)

[
  "configportalscope"
]
CODE

allowedAccessTokenSigningAlgorithms

Signing algorithm for access token. If empty, will use the server default signing algorithm.

Example

[
  "RS256"
]
CODE

userClaims

List of associated user claims that should be included when this resource is requested.

Example

[
  {
    "type": "name",
    "value": "Alice",
    "valueType": "http://www.w3.org/2001/XMLSchema#string"
  }
]
CODE

properties

Gets or sets the custom properties for the resource.

Example

{
  "keyString":"valueString"
}
JSON
API Scope

The API scopes can be defined as the domain of accessibility that an user or another user application has to access the API Resources that the current application exposes. This can be as simple as read and write rights that the user has to access the said API. The client application itself must be aware of all API scopes defined and handle the use cases for each API scopes defined in AuthService.

The API scope has the following configurations:

Item

Description

name

The unique name of the API scope.

Example

configportalscope
JSON

displayName

Display name of the API scope.

Example

Global access to ConfigPortal API
JSON

enabled

Indicates if this API scope resource is enabled. (Default: true).

Example

true
CODE

description

Description of the resource.

Example

Access to ConfigPortal API
CODE

showInDiscoveryDocument

Specifies whether this scope is shown in the discovery document. (Default: true).

Example

true
CODE

required

Specifies whether the user can de-select the scope on the consent screen. (Default: false).

Example

false
JSON

emphasize

Specifies whether the consent screen will emphasize this scope. Use this setting for sensitive or important scopes. (Default: false).

Example

false
JSON

userClaims

List of associated user claims that should be included when this resource is requested.

Example

[
  "name",
  "email",
  "vidispine_user"
]
CODE

properties

Gets or sets the custom properties for the resource.

Example

{
  "keyString":"valueString"
}
JSON
Identity Resource

The identity resources are resources pertaining to the users information that are being collected and used by the client application.

In an Enterprise MAM application, most of these identity resource claims (e.g. vidispine_user) are already defined as required in the documentation and should not be disabled. Optional claims that are not mentioned thereby might be configurable for user consent.

The identity resource has the following configurations:

Item

Description

name

The unique name of the identity resource.

Example

email
JSON

displayName

Display name of the identity resource.

Example

Your email address
JSON

enabled

Indicates if this identity resource is enabled. (Default: true).

Example

true
JSON

description

Description of the resource.

Example

The user's email information
JSON

showInDiscoveryDocument

Specifies whether this scope is shown in the discovery document. (Default: true).

Example

true
CODE

required

Specifies whether the user can de-select the scope on the consent screen. (Default: false).

Example

false
JSON

emphasize

Specifies whether the consent screen will emphasize this scope. Use this setting for sensitive or important scopes. (Default: false).

Example

false
JSON

userClaims

List of associated user claims that should be included when this resource is requested.

Example

[
  "email_verified",
  "email"
]
CODE

properties

Gets or sets the custom properties for the resource.

Example

{
  "keyString":"valueString"
}
JSON

Example

This is example of an real live client configuration:

PUT https://server/vpms3/authservice/v1/Client


body


'{
"absoluteRefreshTokenLifetime": 2592000,
"accessTokenLifetime": 10800,
"accessTokenType": 0,
"allowAccessTokensViaBrowser": true,
"allowOfflineAccess": true,
"allowRememberConsent": true,
"allowedCorsOrigins": [
"https://endpoint:32201",
"https://endpoint:32203",
"https://endpoint:8080"
],
"allowedGrantTypes": [
"implicit"
],
"allowedScopes": [
"openid",
"identityscope",
"profile",
"mediaeditorscope",
"api1",
"configportalscope"
],
"alwaysIncludeUserClaimsInIdToken": true,
"alwaysSendClientClaims": true,
"authorizationCodeLifetime": 30800,
"claims": [
{
"type": "role",
"value": "MP_API_CONSUMER"
},
{
"type": "role",
"value": "CP_API_CONSUMER"
},
{
"type": "client_role",
"value": "CP_API_CONSUMER"
},
{
"type": "mediaportal_user",
"value": "admin"
}
],
"clientClaimsPrefix": "",
"clientId": "mediaeditorfrontend",
"clientName": "VidiEditor Front-end Client",
"clientSecrets": [
{
"description": "Client for VidiEditor GUI",
"value": ""
}
],
"identityTokenLifetime": 3600,
"includeJwtId": false,
"postLogoutRedirectUris": [
"https://endpoint:32201/",
"https://endpoint:32203/",
"https://endpoint:32204/",
"https://endpoint:32205/"
],
"redirectUris": [
"https://endpoint:32201/",
"https://endpoint:32201/assets/silent-refresh.html",
"https://endpoint:32203/",
"https://endpoint:32203/assets/silent-refresh.html",
"https://endpoint:32204/",
"https://endpoint:32204/assets/silent-refresh.html",
"https://endpoint:32205/",
"https://endpoint:32205/assets/silent-refresh.html"
],
"refreshTokenExpiration": 1,
"refreshTokenUsage": 1,
"requireClientSecret": false,
"requireConsent": false,
"slidingRefreshTokenLifetime": 86400,
"updateAccessTokenClaimsOnRefresh": true
}'
CODE