Client¶

A client is a piece of software that requests tokens from Duende IdentityServer - either for authenticating a user (requesting an identity token) or for accessing a resource (requesting an access token). A client must be first registered with Duende IdentityServer before it can request tokens.

Examples for clients are web applications, native mobile or desktop applications, SPAs, server processes etc.

Client configuration contains information related to the environment as some URIs and Origin are stored.

Models¶

A full description of all properties can be found at: https://docs.duendesoftware.com/identityserver/v6/reference/models/client/. Below we cover the most important objects that defines a client.

Client¶

The Client class models an OpenID Connect or OAuth 2.0 client - e.g. a native application, a web application or a JS-based application. The most important property is the ClientIdentifier, a unique ID of the client that must follow the key naming convention.

ClientSecrets¶

List of client secrets - credentials to access the token endpoint.

ClientGrantType¶

ClientGrantType or AllowedGrantTypes specifies the grant types the client is allowed to use; this determines the type of client. See Client Management section below for more information.

ClientRedirectUri¶

ClientRedirectUri specifies the allowed URIs to return tokens or authorization codes to. This is really important for interactive users grant types during the login process; the Uri of the API/website (the client) we are accessing is passed in the request to the authentication server and must match with an Uri defined for this client. A mismatch on those setting will end up in errors of type invalid_client during sign-in process.

ClientScope¶

Or AllowedScopes, by default a client has no access to any resources - specify the allowed resources by adding the corresponding scopes names. Scopes defined here should exists for any resources (API or Identity).

ClientProperty¶

Dictionary to hold any custom client-specific values as needed.

ClientPostLogoutRedirectUri¶

Specifies allowed URIs to redirect to after logout.

ClientIdPRestriction¶

Specifies which external IdPs can be used with this client (if list is empty all IdPs are allowed). Defaults to empty.

ClientCorsOrigin¶

If specified, will be used by Cross-origin resource sharing (CORS) policy service implementations to build a CORS policy for JavaScript clients. CORS is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served. See the OIDC Connect Session Management specification for more details.

The proper definition of Origin can be found at w3.org and is expected to found a collection of origins (scheme://host:port). Previous implementations allowed URL format but it isn't longer supported so review normalize-cors command in sequel-security tool if you're planning upgrade an existing environment. In any case import command in sequel-security will normalize the ClientCorsOrigin by default to match the expected Origin pattern.

Client Claim¶

Allows settings additional Claims for the client. Those will be included in the access token. Each claim key will have the Client claims prefix as prefix and the Type defined in the table.

There are a few additional Claims that can be configured for a client and has a defined meaning. Those Claims can be added using Administration, by clicking on the + Custom Claim button:

See below a list of special Claims:

• dau: Claim that indicates which Username should be used as Default Actioner Username in certain operations that require one.

Sample¶

Clients differ mainly on the grant types that they are allowed to use. Using our JSON specification for representing authentication objects.

As a sample, the security administration SPA website client looks like:

{
    "BackChannelLogoutSessionRequired": true,
    "AlwaysIncludeUserClaimsInIdToken": true,
    "IdentityTokenLifetime": 300,
    "AccessTokenLifetime": 3600,
    "AuthorizationCodeLifetime": 300,
    "AbsoluteRefreshTokenLifetime": 2592000,
    "SlidingRefreshTokenLifetime": 1296000,
    "ConsentLifetime": null,
    "RefreshTokenUsage": 1,
    "UpdateAccessTokenClaimsOnRefresh": false,
    "RefreshTokenExpiration": 1,
    "AccessTokenType": 0,
    "EnableLocalLogin": true,
    "IdentityProviderRestrictions": [],
    "IncludeJwtId": true,
    "Claims": [],
    "AlwaysSendClientClaims": true,
    "ClientClaimsPrefix": "client_",
    "PairWiseSubjectSalt": null,
    "AllowedScopes": [
      "sec.api",
      "sec.authorization",
      "openid",
      "profile"
    ],
    "AllowOfflineAccess": true,
    "Properties": {},
    "BackChannelLogoutUri": null,
    "Enabled": true,
    "ClientId": "sec.app.admin",
    "ProtocolType": "oidc",
    "ClientSecrets": [
      {
        "Description": "Authorization (Security Admin App)",
        "Value": "__ClientSecretHash__",
        "Expiration": null,
        "Type": "SharedSecret"
      }
    ],
    "RequireClientSecret": false,
    "ClientName": "Security Admin App",
    "ClientUri": null,
    "LogoUri": null,
    "AllowedCorsOrigins": [
      "__SecurityApiUrlExternal__"
    ],
    "RequireConsent": false,
    "AllowedGrantTypes": [
      "authorization_code"
    ],
    "RequirePkce": true,
    "AllowPlainTextPkce": false,
    "AllowAccessTokensViaBrowser": true,
    "RedirectUris": [
      "__SecurityAdminUrlExternal__/#/callback#",
      "__SecurityAdminUrlExternal__/#/silentrefresh#"
    ],
    "PostLogoutRedirectUris": [
      "__SecurityAdminUrlExternal__"
    ],
    "FrontChannelLogoutUri": null,
    "FrontChannelLogoutSessionRequired": true,
    "AllowRememberConsent": true
  }

How to manage clients¶

The configuration of clients is a big part of the Authentication server as it allows it to know which APIs, apps, etc. are allowed to ask for authentication and how. Clients can be managed:

• using sequel-security tool, importing and exporting packages.
• using the API,
• using the Administration website.

This resource is protected by Sec.Client securable.

In most of the cases, client configuration are provided by Vanilla configurations of each product and you do not have to manage them. However, there are scenarios like adding new clients for accessing API Gateway where it is required to create clients. Please, refer to each application about how create clients if required.

API client resource¶

The clients resource is exposed at /Authorization/Clients (note this is at Authorization, see how Security Rest API is organized for more information). This is fully documented using Swagger.

Client administration page¶

For managing clients from Administration website:

Go to applications page, an expand the contextual menu of the application you want to manage its clients. Select option Client.

Once at client's page you can create new clients or managing an existing one.

New clients¶

Click on + CLIENT button. Fill in all required settings for the type of client you are creating and save.

For creating a new client is important to fully understand how OpenIdConnect works; with the aim of simplifying this action we have included some typical client configurations below.

Manage existing clients¶

Click on the client you want to manage for opening in read-only mode. Click on edit icon to change or delete it.

Clone existing clients¶

You can also clone existing clients, you just have to click on the desired client to be cloned, go to the top right corner of the window and in the three dots menu select Clone Client.

An exact copy of the client will appear, except for the client ID, client name and client secrets.

Typical client configurations¶

In this section we are going to list the three most typical client configurations and list the minimum information that would need to be filled in the UI for them to work correctly, if any settings aren't mentioned it's because they are not mandatory or can be left as default..

Client credentials¶

The client credentials grant type is used by clients to obtain an access token outside of the context of a user. This is typically used by clients to access resources about themselves rather than to access a user's resources (more info: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/), for example, in Workflow it is used to call the Security Authorization server for a user's specific permissions. For this reason it is typically said it's recommended for machine-to-machine communication (or in this case, more specifically, API-to-API). A clear sample of creating this type of clients is for providing a client to our customers that calls to Sequel Api Gateway.

The minimum information for a client of this type is:

• Grant Types:
  • client_credentials
• Scopes:
  • {APP_KEY}.{SCOPE} (any specific scopes created for your application, e.g. 'wf.api')
• Secrets (one client secret is mandatory to be used for client credentials of type 'SharedSecret')

Authorization code¶

The authorization code grant type for authenticating clients is typically used for SPAs (Single Page Applications). It consists of exchanging an authorization code for an access token and the after that redirects the user via a redirect URL (more info: https://www.oauth.com/oauth2-servers/access-tokens/authorization-code-request/).

So for a client of this type and use, the minimum information needed to be filled in when configuring this client would be:

• Grant Types:
  • authorization_code
  • Require PKCE
  • Allow access token via browser
• Scopes:
  • openid
  • profile
  • {APP_KEY}.{SCOPE} (any specific scopes created for your application, e.g. 'sec.app.admin')
• Redirect URI (one redirect URI is needed so the application knows where to redirect back after requesting a token)
• Allowed CORS origins

Hybrid¶

The hybrid flow is recommended to be used by MVC applications where we have a backend that can securely store passwords and cookies and needs it own token, and then a front end that needs a separate one. Our Workflow MVC application uses this type of client authentication as it needs authentication for the user using the application but also for the calling it's own backend, as would applications like Product Builder, Claims, Origin, etc.

The minimum information for a client of this type would be:

• Grant Types:
  • hybrid
  • Allow access token via browser
• Scopes:
  • openid
  • profile
  • {APP_KEY}.{SCOPE} (any specific scopes created for your application, e.g. 'sec.api')
• Secrets (one client secret is mandatory to be used for the hybrid flow of type 'SharedSecret')