[PREVIEW]  Adding the ability to configure additional scope value for an authentication request

In  elytron security

Overview

OpenID Connect is an authentication mechanism that builds on OAuth 2.0 and allows a user to login to a web application using credentials established by an OpenID provider. Currently, when sending an authentication request to the OpenID provider, one of the required parameters with the authentication code flow is "scope". However, for now, the Elytron OIDC HTTP authentication mechanism hardcodes this value to just "openid" and only allows additional scopes to be specified via a "scope" query parameter.

The OpenID Connect specification indicate that there are other scope values which may be included in the authentication request. This new feature will add the ability to configure the scope attribute of the elytron-oidc-client subsystem under the secure-server and secure-deployment resources, so that additional scope values can be specified when configuring the server or the deployment settings.

The feature will allow the user to specify additional scope values in two ways:

  • In an application’s oidc.json configuration file in the WEB-INF directory of the application,

  • Adding configurations to the elytron-oidc-client subsystem under the secure-deployment and the 'secure-server' resource.

Issue Metadata

Issue

  • N/A

Stability Level

  • Experimental

  • Preview

  • Community

  • default

Dev Contacts

QE Contacts

  • TBD

Testing By

  • Engineering

  • QE

Affected Projects or Components

  • WildFly

  • WildFly Elytron

Other Interested Projects

N/A

Relevant Installation Types

  • Traditional standalone server (unzipped or provisioned by Galleon)

  • Managed domain

  • OpenShift s2i

  • Bootable jar

Requirements

Hard Requirements

  • A new attribute named scope will be added to the secure-deployment and the secure-server resources under the elytron-oidc-client subsystem, which will be used to specify additional scope values. The user can specify the scope values in either resource when setting up the other attributes, such as, client-id and provider-url. These values will be used by the Elytron HTTP OIDC authentication mechanism.

  • It must be possible to configure this attribute using cli commands. For example:

    /subsystem=elytron-oidc-client/secure-deployment=my-secure-deployment:write-attribute(name=scope, value="profile offline_access")

  • It must also be configured by specifying it in the deployment. This can be done using the oidc.json file inside the WEB-INF directory. For example:

    "scope" : "profile email offline_access"

  • The OpenID Connect Specifications contain more details on optional scope values and using scope values to requst Offline Access.

  • The scope value must be a String of space separated values as seen in the examples above.

  • When building the redirect URL, the scopes are to be added at the end as &scope=openid+profile+email+offline_access with the + as the delimiters replacing the spaces.

  • Although OpenID Connect has a small set of scope values outlined in the documentation, there are additional scope values that can be configured depending on the OpenID provider. The scope attribute must accept additional scope values accepted by different OpenID providers.

Nice-to-Have Requirements

N/A

Non-Requirements

N/A

Backwards Compatibility

N/A

Default Configuration

The scope attribute would be undefined by default and in that case, the scope value would be hardcoded as scope=openid as before if the user does not configure any additional scope values.

Test Plan

  • WildFly Elytron test suite: Integration test cases implemented to test for functionality.

  • WildFly test suite: Ensuring the correct scope is specified in the authentication request and used when the scope attribute is changed. The token will be checked for the correct claims obtained using the scope values configured.

  • Tests will be added for both subsystem and deployment configuration.

  • Tests may be added to ensure that the subsystem configuration would fail if the stability level is not defined appropriately.

Community Documentation

Documentation for the new scope option will be added to Elytron OpenID Connect Client Subsystem Configuration.