Web client configuration
Web clients are often websites or portals that run on a server and use OAuth for authentication. They need to be configured via the admin console. This section describes the steps related to configuration of these web clients.
Creating a Web Client
In order to create a new web client, Go to the Configuration
tab of the administration console and click the Web Clients
tab.
On the overview that is shown you can see all the existing web clients.
Note: Web clients are meant for web servers. In this case you or a trusted party is managing the hardware on which this web client runs. We also reference these as static OAuth clients.
To add a new web client, click on the add button. The following form will appear:
Fill all the mandatory fields (marked with *
on the form). The other fields are optional.
Field | Required | Example value | Details |
---|---|---|---|
Name | yes | My demo portal | Display name of this web client. This is only used for informational purposes in the Admin console and APIs. |
Client ID | yes | F167433E63CE8BD877… | Unique identifier of this web client. |
Client secret | yes | AF33E2BF29C54A4639… | Secret to get an Access token. |
Grant types | yes | Authorization code | Supported OAuth grant types for a web client. The available grant types are explained in a section below. |
Access token format | yes | Defines whether the Access token is returned as JSON Web Token (JWT) or as Opaque (random) string. The JWT access token contains the user identifier for grant types Authorization code , Implicit and Resource owner password credentials . |
|
Redirect URL | yes | Location to which the end-user is redirected after successful authorization. This is the full URI to which the end-user is redirected after they have successfully logged in and given authorization for the requested scopes. | |
Additional redirect URLs | no | Additional URIs to which the end-user can be redirected. See "Redirect URL". | |
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 (a.k.a access grant) for an access token. In a common scenario this is done in at most a couple of seconds. Required for grant type Authorization code . |
Access token validity | depends | 3600 | Number of seconds an access token is valid. An access token is the temporary key with which a client can fetch resources. When this period has expired the access token has to be refreshed using a refresh token. Required for grant types Authorization code , Implicit and Client credentials . |
Issue refresh token | no | If this is enabled a refresh token will be issued in case of the authorization code grant type is used. This refresh token can be used by the web client to issue a new access token. | |
Allow simultaneous sessions | no | true | If true, it will allow multiple sessions for the same client, user, and scope to exist at the same time. There are security implications as tokens will exist even after the same credentials are used to log in again. If setting is off, previous sessions are cleaned up when a new one is established. |
Maximum simultaneous sessions | no | 5 | This limits the number of simultaneous sessions when this is enabled. The oldest session is invalidated when the user exceeds the limit. Value must be between 2 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. |
|
Additional audiences | no | aud2, https://example.com | A set of case sensitive strings that identifies the audience of the issued access token besides 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 specified the Token Server will fail the request. | |
Additional scopes | no | The scopes the web client is allowed to request apart from 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 used when a user authenticates for this web client. 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, it can be used in for example 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 on. This should be the URI that all paths for calls to this client should 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 in which 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 may want to notify the user that this web client will have access to his personal information. Which information an 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. |
Additional information about configuration of Scopes and Identity providers can be found in separate chapters.
Description of grant types
Grant types can be configured for a web client.
Grant type | Description |
---|---|
Authorization code | Specifies whether the OAuth client can use the OAuth authorization code grant type in order to allow this web client to request an access token on behalf of the end-user. |
Implicit | Use this grant type with caution as the access token is directly returned to the browser of the end-user in the redirect upon successful authorization. |
Client credentials | Specifies whether a web client can use its client credentials to request an access token. Note that this access token is not linked to a user since it's solely requested by the web client without any user interaction. This function is typically used for machine-to-machine communication. |
Resource owner password credentials | Refer to the documentation for Resource owner password credentials for more information. |
Validate access token | This Grant type has been deprecated. This allows a Web client to validate an Access token and get additional information about it. See the topic on configuration of a resource gateway. |
Enabling OpenID Connect capability
In order to enable OpenID Connect capability add openid
scope either as Default scopes
or Additional scopes
. This activates a second step of the Web Client config:
Field | Required | Example value | Details |
---|---|---|---|
ID Token validity | yes | 3600 | Number of seconds an ID Token is valid. It is used to calculate the exp expiration date claim in the ID token. |
Additional Audiences | no | https://resource.example.com | A set of case sensitive strings that identifies who is the audience of the issued ID Token. It is used to populate aud claim in the ID Token in combination with the Client ID which is always included. |
Post Logout Redirect URL | no | https://redirect.example.com | This is Primary/Default Post Logout URL. The user will be redirected to this URL if no other URL is specified in the end session request. |
Additional Post Logout Redirect URLs | no | https://redirect.example.com, https://postlogout.example.com | A list of additional Post Logout Redirect URLs. This list contains the potential URLs that could be specified to be redirected to as part of the end session request. |
Front-Channel Logout URL | no | https://frontchannellogout.example.com | A URL reachable on the Relying Party that will invalidate the session. This will be triggered after a successful logout via the end session page. |
ID Token Encryption enabled | no | Enabling/Disabling ID Token encryption | |
Encryption Method | depends | A256GCM | Encryption Method used to encrypt ID Token. Required when ID token Encryption Enabled is checked. |
JWKS URI | depends | https://example.com/jwks.json | JSON Web Key Set (JWKS) endpoint which contains JSON Web Keys (JWK) used to encrypt the ID Token. Required when ID Token Encryption enabled is checked. |
For additional information on the use of the Redirect and Front Channel URLs, refer to the end session guide
Removing a web client
In order to remove a web client, Go to the Configuration
tab of the administration console and click the Web Clients
tab. On the list of web client find
the one you want to remove and click the delete button on the right (You will be asked to confirm you decision).