Skip to content

User Documentation

Jump to bottom
H2CK edited this page May 24, 2024 · 7 revisions

Nextcloud OIDC App - User Documentation

This is an OIDC Provider App for Nextcloud. This application allows to use your Nextcloud Login at other services supporting OpenID Connect.

Provided features:

  • Support for OpenID Connect Code (response_type = code) and Implicit (response_type = id_token) Flow - Implicit Flow must be activated per client.
  • Configuration of accepted client for whom JWT Tokens are provided. Public and confidential types are supported.
  • Creation of JWT Token with claims based on requested scope. (Currently supported scopes openid, profile, email, roles and groups)
  • Supported signing algorithms RS256 (default) and HS256
  • Group memberships are passed as roles in JWT token.
  • Clients can be assigned to dedicated user groups. Only users in the configured group are allowed to retrieve an access token to fetch the JWT.
  • Discovery endpoint provided
  • Logout endpoint
  • Dynamic Client Registration

Configuration

It is possible to modify the settings of this application in Nextcloud admin settings in the section security. There you find the an area with the headline 'OpenID Connect clients'.

In this area you can:

  • Add/Modify/Remove Clients
  • Add/Modify/Remove Logout URLs
  • Change some overall settings
  • Regenerate your public/private key for signeing the id token.

Endpoints

The following endpoint are available below index.php/apps/oidc/:

  • Discovery: openid-configuration (GET) or at index.php/.well-known/openid-configuration
  • WebFinger: at index.php/.well-known/webfinger
  • Authorization: authorize(GET)
  • Token: token(POST) - Credentials for authentication can be passed via Authorization header or in body. (Ususally the Authorization header is fetched directly by the Nextcloud server itself and is not passed to the oidc application. To allow the use of this mechanism a pseudo user backend is provided. Nevertheless this causes an exception shown in the logs on each login using the Authorization header.)
  • UserInfo: userinfo(GET / POST - Authentication with previously retrieved access token)
  • JWKS: jwks(GET)
  • Logout: logout (GET)
  • Dynamic Client Registration: register (POST) - Disabled by default. Must be enabled in settings.

CORS is enable for all domains on all the above endpoints.

The discovery and web finger endpoint should be made available at the URL: <Issuer>/.well-known/openid-configuration. You may have to configure your web server to redirect this url to the discovery endpoint at <Issuer>/index.php/apps/oidc/openid-configuration (or <Issuer>/index.php/.well-known/openid-configuration). For web finger there should be a redirect to <Issuer>/index.php/.well-known/webfinger.

Logout Details

To support logout functionality the discovery enpoint contains the attribute end_session_endpointto announce the support for RP-Initiated logout. The current implementation only partially supports this specification.

Current limitations:

  • Only GET requests to logout endpoint are supported (POST might be added in future)
  • Only the optional attributes id_token_hint, client_id and post_logout_redirect_uri are supported

Remark on post_logout_redirect_uri: The passed URIs are checked against the list of allowed logout redirect URIs from the app configuration. The provided post_logout_redirect_uri must start with one of the configured URIs. If no post_logout_redirect_uri is passed or the post_logout_redirect_uri does not match any allowed redirect URI, there will be a redirect to the login page of the Nextcloud instance.

Up to now there is NO support for:

Dynamic Client Registration Details

It is possible to use the dynamic client registration according to OpenID Connect Dynamic Client Registration 1.0. To use this feature you have to enable it in the settings of this application (see above).

Due to security reasons there is a BruteForce throttleing as well as a limitation of dynamically registered clients to 100. Additionally a dynamically registered client is only valid for 3600 seconds. Both parameters can currently not be changed via the settings. The registration endpoint is accessible for everybody without any authentication and authorization. So please enable this feature with the possible thread in mind.

Scopes

Scope Description
openid Default scope. Will be added if missing. Information about the user is provided as user id in the claims preferred_username and sub.
profile Adds the claims name, address, phone_numberand updated_atto the ID Token. address and phone_number are only available, if those attributes are set in the users profile in Nextcloud. The claim name contains the display name as configured in the users profile in Nextcloud. If no display name is set the username is provided in this claim. If enabled in the app settings it is also possible to generate the claim picture with users avatar encoded in a data url. Caution: If enabled for the id token this might lead to very large id token, even if the picture size is limited to 64px.
email Adds the email address of the user to the claim email. Furthermore the claim email_verified is added.
roles Adds the groups of the user in the claim roles.
groups Adds the groups of the user in the claim groups.

Limitations

Currently it is not yet possible to use an issued Access Token or ID Token to access resources at the Nextcloud instance it self. (Future implementation planned)

Usage Example

Apache Module mod_auth_openidc

Following an example configuration how to use this app with the Apache module mod_auth_openidc

OIDCProviderMetadataURL https://my.nextcloud-instance.com/.well-known/openid-configuration
OIDCRedirectURI https://my.other-service.com:443/oidc/callback

OIDCClientID <client_id from settings>
OIDCClientSecret <client_secret from settings>
OIDCProviderTokenEndpointAuth client_secret_post

OIDCRemoteUserClaim preferred_username
OIDCScope "openid profile email roles“
Clone this wiki locally