This document covers some important configuration elements of client configuration. How these elements are configured for a client has an impact on aspects like client security.
Redirect URI is the most basic and at times the only parameter needed for registering a client. It is defined in OAuth framework and OpenId Connect specification.
The client can register a list of URIs as a value for redirect URI parameter. Redirect URI can be any valid URI.
- Redirect URI should be an absolute URI. For instance, URI should not have wildcard characters. As recommended here
- Redirect Regex: Janssen Server enables clients to allow redirect URIs that conform to a regular expression(regex)
pattern. While validating redirect URIs received in an incoming request, the Janssen Server first looks at the list
of statically registered URI as part of
Redirect URIsand then checks if any of the redirect URI from the request matches with the regex provided by the client. Great care should be exercised when using regex to ensure that it accurately matches with the intended patterns only. This feature can be turned on or off via feature flag
- When using client type as
web, the redirect URI generally takes the form of
<schema>://<host-name>:<port>/<path>. It must use
httpsschema. The exception to schema rule is made when
localhostor loopback ip
127.0.0.1is used as the hostname.
- Prefer to use the loopback IP instead of
localhostas hostname to facilitate local testing as recommended in OAuth 2.0 native app specification section 8.3
- Janssen Server supports all methods of redirection used by
native apps. Use of Private-Use URI (or custom URL) is
supported by allowing redirect URI to take the form of reverse DNS name, for example,
com.example.app. URLs for loopback interface redirection are also supported.
- When the client registers multiple redirect URIs (Janssen Server accepts a list of URIs separated by space), be aware that Janssen Server will use these, one by one for validation purposes and the validation stops at the first match.
- If there are multiple registered redirect_uris, and the client is using
pairwisesubject identifiers, the Client MUST also register a sector_identifier_uri. This is required to keep the pairwise subject identifiers consistent across various domains under the same administrative control. Refer to pairwise algorithm section of OpenId Connect specification for more details.
Janssen Server allows clients to configure static set of keys using
JWKS or specify a URI as
JWKS URI where client
is exposing its key set. For client who can host keys and expose a URI, it is recommended to use
JWKS URI instead of
JWKS key set. Using
JWKS URI enables client to rotate its cryptographic keys without having to change the
client configuration on Janssen Server.
Available Algorithms for Encryption and Signing#
The client can select algorithms for cryptographic and encryption during client configuration. Janssen Server supports a list of algorithms as listed in response of Janssen Server's well-known configuration endpoint given below.
Claims that list supported algorithms:
- RSA keys with a minimum 2048 bits if using RSA cryptography
- Elliptic Curve keys with a minimum of 160 bits if using Elliptic Curve cryptography
- Client secret should have a minimum of 128 bits if using symmetric key cryptography
- Sign with PS256 (RSASSA-PSS using SHA-256 and MGF1 with SHA-256) or ES256 (ECDSA using P-256 and SHA-256)
Supported Grant Types#
Grant defines how a client interacts with the token endpoint to get the tokens. Janssen Server supports grant types defined by OAuth 2.0, OAuth 2.1, and extension grants defined by other RFCs. A complete list of supported grant types can be found in the response of the Janssen Server's well-known configuration endpoint given below.
grant_types_supported lists all the supported grant types in the response.
Configuring Grant Type For Client#
Janssen Server will allow requests from a client with grant types that the client is configured to use. Client can be configured to use or not use certain grant types using CLI or TUI tools.
Recommendations For Using Grant Types and Flows#
Developers should use the grant types based on the ability of the client to protect the client credentials as well as
the security profile of the deployment. If the client software is a server-side component that can securely store the
client credentials, such a client is called a
confidential client. As opposed to that, if the application requesting
access token is entirely running on a browser, where it is not possible to store client credentials securely, such a client
is called a
Along with the grant type to be used, developers also need to choose which flow should be used to get the required tokens. The table below shows grant types and flows that should be used for various use-cases.
|Client Type||Recommended Grant Type||Flow|
|Backend App (Example: batch processes) that need to access its own resources||
|Server backend of a web-application needs access token||
|Web-application that needs user information via id_token on browser and access token on backend||
|Browser based single page applications or Mobile applications||
||Authorization Code with PKCE|
|Browser based single page applications or Mobile applications that only intend to get id_token||-||Implicit Flow with Form Post|
|Input constrained devices (Example: TV)||
|Highly trusted applications where redirect based flows are not feasible to implement||
||Resource Owner Password Flow|
Certain grant types should not be used together. For example, implicit flow with hybrid flow. Or using authorization code flow with hybrid flow. This allows a downgrade attack from more secure flow to less secure flow.
If the OAuth authorization prompt should not be displayed to end users, set this field to True. This is useful for SSO to internal clients (not a third party) where there is no need to prompt the person to approve the release of information.
response_type request parameter when sending request to authorization endpoint. Using this parameter, the
client informs the authorization server of the desired grant. Response type parameter is
defined in the OAuth 2.0 framework.
Janssen Server supports response types defined by OAuth 2.0, OAuth 2.1.The complete list of supported response types can be found in the response of the Janssen Server's well-known configuration endpoint given below.
response_types_supported lists all the supported grant types in the response.
When registering client using dynamic client registration, if the
response_type parameter is not specified, it'll
Response Type Recommendations#
- Avoid using response type
token. This response type is deprecated by OAuth 2.1.
- Grant types allowed for a client determines which response types are permitted in authorization requests. Make sure appropriate grant types are configured in Janssen Server client configuration. Janssen Server will reject authorization requests containing response types not permitted for respective client.
If you’d like to contribute to this document, get started with the Contribution Guide