Skip to main content
Skip table of contents

Configure OIDC Client Applications [C IG]

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 /Client API

The configuration properties for /Client are as follows:

Item

Description

clientId

Unique ID of the client.

Example

CODE
configportalclient

clientName

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

Example

CODE
ConfigPortal UI

clientUri

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

Example

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

logoUri

URI to client logo (used on consent screen).

Example

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

enabled

Specifies if client is enabled (Default: true).

Example

CODE
true

protocolType

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

Example

JSON
oidc

description

Description of the client application.

Example

CODE
This is the config portal web ui application. 

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

CODE
300

accessTokenLifetime

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

Example

CODE
3600

authorizationCodeLifetime

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

Example

CODE
300

absoluteRefreshTokenLifetime

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

Example

CODE
2592000

slidingRefreshTokenLifetime

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

Example

JSON
1296000

consentLifetime

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

Example

JSON
300

userSsoLifetime

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

Example

JSON
300

deviceCodeLifetime

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

Example

CODE
300

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

JSON
false

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

JSON
true

includeJwtId

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

Example

JSON
true

requireClientSecret

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

Example

JSON
true

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

JSON
false

allowRememberConsent

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

Example

JSON
true

requirePkce

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

Example

JSON
true

allowPlainTextPkce

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

Example

JSON
false

requireRequestObject

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

Example

JSON
false

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

JSON
false

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

JSON
false

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

CODE
client_

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

JSON
false

allowOfflineAccess

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

Example

CODE
false

frontChannelLogoutUri

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

Example

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

frontChannelLogoutSessionRequired

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

Example

JSON
true

backChannelLogoutUri

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

Example

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

backChannelLogoutSessionRequired

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

Example

JSON
true

clientSecrets

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

Example

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

redirectUris

Specifies allowed URIs to return tokens or authorization codes to.

Example

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

postLogoutRedirectUris

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

Example

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

allowedCorsOrigins

Gets or sets the allowed CORS origins for client applications.

Example

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

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.

JSON
[
  "implicit"
]

allowedScopes

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

Example

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

allowedIdentityTokenSigningAlgorithms

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

Example

JSON
[
  "RS256"
]

identityProviderRestrictions

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

Example

JSON
[
  "Facebook"
]

claims

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

Example

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

properties

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

Example

JSON
{
  "keyString":"valueString"
}

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 /Resource/ApiResource API

The API resource has the following configurations:

Item

Description

name

The unique name of the API resource.

Example

CODE
configPortalApi

displayName

Display name of the API resource.

Example

CODE
Config Portal API

enabled

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

Example

CODE
true

description

Description of the resource.

Example

CODE
Access to ConfigPortal API

showInDiscoveryDocument

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

Example

CODE
true

apiSecrets

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

Example

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

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)

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

v2 (References the ApiScope name)

CODE
[
  "configportalscope"
]

allowedAccessTokenSigningAlgorithms

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

Example

CODE
[
  "RS256"
]

userClaims

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

Example

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

properties

Gets or sets the custom properties for the resource.

Example

JSON
{
  "keyString":"valueString"
}
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 /Resource/ApiScope API

The API scope has the following configurations:

Item

Description

name

The unique name of the API scope.

Example

JSON
configportalscope

displayName

Display name of the API scope.

Example

JSON
Global access to ConfigPortal API

enabled

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

Example

CODE
true

description

Description of the resource.

Example

CODE
Access to ConfigPortal API

showInDiscoveryDocument

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

Example

CODE
true

required

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

Example

JSON
false

emphasize

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

Example

JSON
false

userClaims

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

Example

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

properties

Gets or sets the custom properties for the resource.

Example

JSON
{
  "keyString":"valueString"
}
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 /Resource/IdentityResource API

The identity resource has the following configurations:

Item

Description

name

The unique name of the identity resource.

Example

JSON
email

displayName

Display name of the identity resource.

Example

JSON
Your email address

enabled

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

Example

JSON
true

description

Description of the resource.

Example

JSON
The user's email information

showInDiscoveryDocument

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

Example

CODE
true

required

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

Example

JSON
false

emphasize

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

Example

JSON
false

userClaims

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

Example

CODE
[
  "email_verified",
  "email"
]

properties

Gets or sets the custom properties for the resource.

Example

JSON
{
  "keyString":"valueString"
}

Example

This is example of an real live client configuration:

CODE
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
}'

JavaScript errors detected

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

If this problem persists, please contact our support.