Web clients
A web client is an OAuth client or an OpenID Connect Relying Party that is registered up front. Mobile applications are registered dynamically.
Web clients are often websites or portals that run on a server and use OAuth for authentication. They can also be used for standalone applications that are installed on users' devices, if the applications require OAuth authorization. Configure web clients on the admin console.
Create a web client
To create a new web client, on the administration console, go to the Configuration tab and select the Web Clients tab. The overview shows all the existing web clients.
Note
Web clients are meant for web servers or fat clients. In this case, you or a trusted party manages the hardware that this web client runs on. These are also referred to as static OAuth clients.
To add a new web client, click the add button. The following form is displayed:
Fill all the mandatory fields. The other fields are optional.
| Field | Required | Example value | Details |
|---|---|---|---|
| Name | yes | My demo portal | The display name of the web client is used only for information purposes in the admin console and APIs. |
| Client ID | yes | F167433E63CE8BD877… | Unique identifier of this web client |
| Authentication method | yes | Client secret | The options are Client secret for confidential clients using a secret, Private key JWT for confidential clients using self-signed client assertions, or Public for clients without authentication. Client secret requires you to enter a predefined secret in this configuration. A public client using the Authorization code grant type is required to use PKCE. (See Proof Key for Code Exchange.) |
| Client secret | depends | AF33E2BF29C54A4639… | Secret to get an access token. Required when the authentication method is Client secret. |
| Dynamic JWT Configuration | depends | http://site.com/jwks | JWKS URI with public keys for private key JWT authentication. Required when the authentication method is Private key JWT and the dynamic JWKS source is chosen. |
| Static JWT Configuration | depends | Plain public key for private key JWT authentication. Required when the authentication method is Private key JWT and the plain public key JWKS source is chosen. | |
| Grant types | yes | Authorization code | Supported OAuth grant types for a web client. |
| Access token format | yes | Defines whether the Access token is returned as JSON Web Token (JWT) or as an Opaque (random) string. The JWT access token contains the user identifier for the Authorization code grant type. | |
| Redirect URL | depends | This is the full URI that the user is redirected to after they have successfully logged in and given authorization for the requested scopes. It is required for the Authorization code grant type. | |
| Additional redirect URLs | no | Additional URIs that the user can be redirected to. | |
| Device Verification URL | no | https://example.com/device | A URL that the user is redirected to by the device to complete the authorization flow. It is used for the DEVICE_CODE grant type with in-app authorization. It is expected that the user manually enters the user code. |
| Complete Device Verification URL | no | https://example.com/device?code= | A URL that the user is redirected to by the device to complete the authorization flow. It is used for the DEVICE_CODE grant type with in-app authorization. The {user_code} is replaced with the actual user code. |
| Access grant validity | depends | 30 | Number of seconds an access grant is valid. This is the time a client has to exchange an authorization grant (access grant) for an access token. This is typically done in at most a couple of seconds. Required for the Authorization code grant type. |
| Access token validity | depends | 3600 | Number of seconds an access token is valid. An access token is the temporary key that a client can fetch resources with. When this period expires, the access token must be refreshed using a refresh token. Required for the Authorization code and Client credentials grant types. |
| Issue refresh token | no | If this is enabled, a refresh token is issued when the authorization code grant type is used. The web client can use this refresh token to issue a new access token. | |
| Refresh token validity | no | 7200 | Limits the time that refresh tokens can be used to obtain a new access token and refresh token, calculated from the initially-issued access token. For infinite refresh token usage, leave empty. Available when Issue refresh token is set to true. |
| Allow simultaneous sessions | no | true | If true, it allows multiple sessions for the same client, user, and scope to exist at the same time. There are security implications because tokens exist even after the same credentials are used to log in again. If this setting is off, previous sessions are cleaned up when a new one is established. |
| Maximum simultaneous sessions | no | 5 | When enabled, it limits the number of simultaneous sessions. The oldest session is invalidated when the user exceeds the limit. Value must be between two and 25 (inclusive). |
| Audience: Resource gateways | no | The resource gateways that validate the access tokens. It is used to populate the aud claim in a JWT access token. | |
| Delegated Administration configuration | no | myDabpConfig | Configuration of delegated administration that should be used to gather person report containing information about group memberships and permissions. |
| Group permissions version | no | By default, the latest version of the DABP person report is returned in claims. Change the default to legacy if your application depends on the legacy version 1 of this report. | |
| Additional audiences | no | aud2, https://example.com | A set of case-sensitive strings that identify the audience of the issued access token, except the resource gateways. It is used to populate the aud claim in a JWT access token. |
| Default scopes | no | The scopes that are assigned to an authorization request if no scopes are requested. If no scopes are requested by the web client in the authorization request, and no defaults are specified, the OneWelcome Identity Platform fails the request. | |
| Additional scopes | no | The scopes that the web client is allowed to request, except the default scopes. The default scopes are also counted as scopes that can be requested by a web client. | |
| Identity provider | depends | myIdp | The identity provider that is used when a user authenticates for this web client. Normally, this is a browser-based identity provider, but for scenarios where custom registration is used, it can also be a custom API-based identity provider. See the Identity Provider configuration topic. |
| Additional Identity provider(s) | no | addIdp1, addIdp2 | Additional identity providers that can be used when a user authenticates with this application. A primary must be specified if additional are entered. |
| Logo URI | no | URI of the logo for this web client. For example, it can be used in the consent screen. | |
| Public base URI | no | When the client has the deprecated grant type Validate access token, it has some URI where it can be reached. This is the URI that all paths for calls to this client start with. |
|
| Template set | no | payment-app | Every web client can have its own branding. Therefore multiple sets of templates are supported. The prefix corresponds to the directory where a set of templates is stored. |
| Skip Consent page | no | true | In the OAuth flow consent is requested because a web client requests access to the user's data. When the web client is managed by a third party, you might want to notify the user that this web client has access to his personal information. Which information a web client has access to is defined by the requested scopes. When consent is disabled, the user is not required to give consent for the web client during the authorization process. |
For more information about the configuration, see scopes, identity providers, and authentication methods.
To enable the OpenID Connect capability, add the scope openid to either Default scopes or Additional scopes. This activates a second step of the Web Client
config: OpenID Relying Party configuration.
Grant types
Grant types can be configured for a web client.
-
Authorization code specifies whether the OAuth client can use the OAuth authorization code grant type, to allow this web client to request an access token on behalf of the user. This is the only grant type that is allowed for public clients using PKCE as the authentication method.
-
Client credentials specify whether a web client can use its client credentials to request an access token. This access token is not linked to a user because it's solely requested by the web client without any user interaction. This function is typically used for machine-to-machine communication.
-
Device code specifies whether a web client can use the OAuth Device Code Flow to allow this web client to request an access token on behalf of the user. This grant type is used for devices that do not have a browser or that have limited input capabilities.
-
Resource owner password credentials specifies whether a web client can use the OAuth Resource Owner Password Credentials grant type to allow this web client to request an access token on behalf of the user. This grant type is not recommended and should be avoided if possible. See the topic on resource owner password credentials for more information.
-
Implicit Use this grant type with caution because, upon successful authorization, the access token is returned directly to the user's browser in the redirect. This flow is no longer recommended. It is advised to use the authorization code grant in combination with PKCE.
Removing a web client
To remove a web client, on the administration console, go to the Configuration tab and click the Web Clients tab. In the list of web clients, find the one you want to remove and click the delete button on the right.
