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:
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.
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.
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:
For authorization and authentication to happen, the client application would be expected to always send an authorization request either of the following endpoints:
authorize endpoint for the implicit flow
token endpoint for the authorization code and client credentials flow
This might be already handled automatically by the third-party client side libraries. Please do refer to their documentation for specific details.
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
CODE
|
clientName | Client display name (used for logging and consent screen). Example
CODE
|
clientUri | URI to further information about client (used on consent screen). Example
CODE
|
logoUri | URI to client logo (used on consent screen). Example
CODE
|
enabled | Specifies if client is enabled (Default: true). Example
CODE
|
protocolType | Gets or sets the protocol type. (Default: oidc) Example
JSON
|
description | Description of the client application. Example
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
CODE
|
accessTokenLifetime | Lifetime of access token in seconds (Default: 3600 seconds / 1 hour). Example
CODE
|
authorizationCodeLifetime | Lifetime of authorization code in seconds (Default: 300 seconds / 5 minutes). Example
CODE
|
absoluteRefreshTokenLifetime | Maximum lifetime of a refresh token in seconds. (Default: 2592000 seconds / 30 days). Example
CODE
|
slidingRefreshTokenLifetime | Sliding lifetime of a refresh token in seconds. (Default: 1296000 seconds / 15 days). Example
JSON
|
consentLifetime | Lifetime of a user consent in seconds. (Default: null (no expiration)) Example
JSON
|
userSsoLifetime | The maximum duration (in seconds) since the last time the user authenticated. (Default: null (no expiration)) Example
JSON
|
deviceCodeLifetime | Gets or sets the device code lifetime (Default: 300). Example
CODE
|
refreshTokenUsage | Determines whether the Refresh Token should be reused. (Default: 1)
|
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
|
refreshTokenExpiration | Determines the type of Refresh Token. (Default: 1)
|
accessTokenType | Specifies whether the access token is a self contained JWT token or reference token (Default: 0).
|
enableLocalLogin | Gets or sets a value indicating whether the local login is allowed for this client. (Default: true). Example
JSON
|
includeJwtId | Gets or sets a value indicating whether JWT access tokens should include an identifier. (Default: true). Example
JSON
|
requireClientSecret | If set to false, no client secret is needed to request tokens at the token endpoint. (Default: true). Example
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
JSON
|
allowRememberConsent | Specifies whether user can choose to store consent decisions. (Default: true). Example
JSON
|
requirePkce | Specifies whether a proof key is required for authorization code based token requests. (Default: true). Example
JSON
|
allowPlainTextPkce | Specifies whether a proof key can be sent using plain method. (not recommended and defaults to false). Example
JSON
|
requireRequestObject | Specifies whether the client must use a request object on authorize requests. (Default: false). Example
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
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
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
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
JSON
|
allowOfflineAccess | Gets or sets a value indicating whether to allow offline access. (Default: false). Example
CODE
|
frontChannelLogoutUri | Specifies logout URI at client for HTTP front-channel based logout. Example
JSON
|
frontChannelLogoutSessionRequired | Specifies is the user's session id should be sent to the Example
JSON
|
backChannelLogoutUri | Specifies logout URI at client for HTTP back-channel based logout. Example
JSON
|
backChannelLogoutSessionRequired | Specifies is the user's session id should be sent to the Example
JSON
|
clientSecrets | Set a collection of secret keys for flows that require secrets to authenticate against. Example
JSON
|
redirectUris | Specifies allowed URIs to return tokens or authorization codes to. Example
JSON
|
postLogoutRedirectUris | Specifies allowed URIs to redirect to after logout. See the OIDC Connect Session Management spec for more details. Example
JSON
|
allowedCorsOrigins | Gets or sets the allowed CORS origins for client applications. Example
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.
JSON
|
allowedScopes | Specifies the API scopes that the client is allowed to request. If empty, the client can't access any scope. Example
JSON
|
allowedIdentityTokenSigningAlgorithms | Signing algorithm for identity token. If empty, will use the server default signing algorithm. (Default: []) Example
JSON
|
identityProviderRestrictions | Specifies which external Identity Providers (IdPs) can be used with this client (if list is empty all IdPs are allowed). (Default: ""). Example
JSON
|
claims | Allows settings claims for this client (will be included in the access token). Example
JSON
|
properties | Gets or sets the custom properties for the client. (Default: {}) Example
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
CODE
|
displayName | Display name of the API resource. Example
CODE
|
enabled | Indicates if this resource is enabled. (Default: true). Example
CODE
|
description | Description of the resource. Example
CODE
|
showInDiscoveryDocument | Specifies whether this scope is shown in the discovery document. (Default: true). Example
CODE
|
apiSecrets | The API secret is used for the introspection endpoint. The API can authenticate with introspection using the API name and secret. Example
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)
JSON
v2 (References the ApiScope name)
CODE
|
allowedAccessTokenSigningAlgorithms | Signing algorithm for access token. If empty, will use the server default signing algorithm. Example
CODE
|
userClaims | List of associated user claims that should be included when this resource is requested. Example
CODE
|
properties | Gets or sets the custom properties for the resource. Example
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
JSON
|
displayName | Display name of the API scope. Example
JSON
|
enabled | Indicates if this API scope resource is enabled. (Default: true). Example
CODE
|
description | Description of the resource. Example
CODE
|
showInDiscoveryDocument | Specifies whether this scope is shown in the discovery document. (Default: true). Example
CODE
|
required | Specifies whether the user can de-select the scope on the consent screen. (Default: false). Example
JSON
|
emphasize | Specifies whether the consent screen will emphasize this scope. Use this setting for sensitive or important scopes. (Default: false). Example
JSON
|
userClaims | List of associated user claims that should be included when this resource is requested. Example
CODE
|
properties | Gets or sets the custom properties for the resource. Example
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
JSON
|
displayName | Display name of the identity resource. Example
JSON
|
enabled | Indicates if this identity resource is enabled. (Default: true). Example
JSON
|
description | Description of the resource. Example
JSON
|
showInDiscoveryDocument | Specifies whether this scope is shown in the discovery document. (Default: true). Example
CODE
|
required | Specifies whether the user can de-select the scope on the consent screen. (Default: false). Example
JSON
|
emphasize | Specifies whether the consent screen will emphasize this scope. Use this setting for sensitive or important scopes. (Default: false). Example
JSON
|
userClaims | List of associated user claims that should be included when this resource is requested. Example
CODE
|
properties | Gets or sets the custom properties for the resource. Example
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
}'