{"id":15051226,"url":"https://github.com/nextcloud/user_oidc","last_synced_at":"2025-04-04T22:06:51.684Z","repository":{"id":36985534,"uuid":"259256400","full_name":"nextcloud/user_oidc","owner":"nextcloud","description":"OIDC connect user backend for Nextcloud","archived":false,"fork":false,"pushed_at":"2025-03-28T02:05:58.000Z","size":6333,"stargazers_count":100,"open_issues_count":80,"forks_count":39,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-28T03:19:31.805Z","etag":null,"topics":["hacktoberfest","nextcloud","openid-connect"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nextcloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-27T08:45:24.000Z","updated_at":"2025-03-28T02:06:02.000Z","dependencies_parsed_at":"2023-02-17T01:10:39.223Z","dependency_job_id":"e3a00105-74d3-4679-bb2d-91ff1fde156b","html_url":"https://github.com/nextcloud/user_oidc","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fuser_oidc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fuser_oidc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fuser_oidc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fuser_oidc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nextcloud","download_url":"https://codeload.github.com/nextcloud/user_oidc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","nextcloud","openid-connect"],"created_at":"2024-09-24T21:31:59.871Z","updated_at":"2025-04-04T22:06:51.663Z","avatar_url":"https://github.com/nextcloud.png","language":"PHP","readme":"\u003c!--\n  - SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors\n  - SPDX-License-Identifier: AGPL-3.0-or-later\n--\u003e\n# user_oidc\n\n[![REUSE status](https://api.reuse.software/badge/github.com/nextcloud/user_oidc)](https://api.reuse.software/info/github.com/nextcloud/user_oidc)\n\nOpenID Connect user backend for Nextcloud\n\n## General usage\nSee [Nextcloud and OpenID-Connect](https://web.archive.org/web/20240412121655/https://www.schiessle.org/articles/2023/07/04/nextcloud-and-openid-connect/)\nfor a proper jumpstart.\n\n### User IDs\n\nThe OpenID Connect backend will ensure that user ids are unique even when multiple providers would report the same user\nid to ensure that a user cannot identify for the same Nextcloud account through different providers.\nTherefore, a hash of the provider id and the user id is used. This behaviour can be turned off in the provider options.\n\n## Commandline settings\nThe app could also be configured by commandline.\n\n### Provider entries\nProviders are located by provider identifier.\n\nTo list all configured providers, use:\n```\nsudo -u www-data php /var/www/nextcloud/occ user_oidc:provider\n```\n\nTo show detailed provider configuration, use:\n```\nsudo -u www-data php /var/www/nextcloud/occ user_oidc:provider demoprovider\n```\n\nA provider is created if none with the given identifier exists and all parameters are given:\n```\nsudo -u www-data php /var/www/nextcloud/occ user_oidc:provider demoprovider --clientid=\"WBXCa003871\" \\\n    --clientsecret=\"lbXy***********\" --discoveryuri=\"https://accounts.example.com/openid-configuration\"\n```\n\nOther options like attribute mappings or group provisioning can be optionally specified. For more details refer to `occ user_oidc:provider --help`.\n\nTo delete a provider, use:\n```\nsudo -u www-data php /var/www/nextcloud/occ user_oidc:provider:delete demoprovider\n  Are you sure you want to delete OpenID Provider demoprovider\n  and may invalidate all assiciated user accounts.\n```\nTo skip the confirmation, use `--force`.\n\n***Warning***: be careful with the deletion of a provider because in some setup, this invalidates access to all\nNextCloud accounts associated with this provider.\n\n#### Avatar support\n\nThe avatar attribute on your IdP side may contain a URL pointing to an image file or directly a base64 encoded image.\nThe base64 should start with `data:image/png;base64,` or `data:image/jpeg;base64,`.\nThe image should be in JPG or PNG format and have the same width and height.\n\n### Custom login button label\n\nYou can set a custom label for the buttons in the login page.\n\nSet this value in `config.php`:\n``` php\n'user_oidc' =\u003e [\n    'login_label' =\u003e 'Connect with {name}',\n],\n```\nThis custom label won't be translated.\n\n### Disable default claims\n\nEven if you don't map any attribute for quota, display name, email or groups, this application will\nask for the 'quota', 'name', 'email', 'groups' claims and map them to an attribute with the same name.\n\nTo change this behaviour and disable the default claims, you can change this value in `config.php`:\n``` php\n'user_oidc' =\u003e [\n    'enable_default_claims' =\u003e false,\n],\n```\n\nWhen default claims are disabled, each claim will be asked for only if there is an attribute explicitely mapped\nin the OpenId client settings (in Nextcloud's admin settings).\n\n### ID4me option\nID4me is an application setting switch which is configurable as normal Nextcloud app setting:\n```\nsudo -u www-data php /var/www/nextcloud/occ config:app:set --value=1 user_oidc id4me_enabled\n```\n\n### Disable other login methods\nIf there is only one OpenID Connect provider configured, it can be made the default login\nmethod and the user would get redirected to the provider immediately for the\nlogin. Admins can still use the regular login through adding the `?direct=1`\nparameter to the login URL.\n\n```bash\nsudo -u www-data php var/www/nextcloud/occ config:app:set --value=0 user_oidc allow_multiple_user_backends\n```\n\n### PKCE\n\nThis app supports PKCE (Proof Key for Code Exchange).\nhttps://datatracker.ietf.org/doc/html/rfc7636\nUnless PKCE is not supported by the configured OpenID Connect provider,\nit is enabled by default.\nYou can also manually disable it in `config.php`:\n``` php\n'user_oidc' =\u003e [\n    'use_pkce' =\u003e false,\n],\n```\n\n### Single logout\n\nSingle logout is enabled by default. When logging out of Nextcloud,\nthe end_session_endpoint of the OpenID Connect provider is requested to end the session on this side.\n\nIt can be disabled in `config.php`:\n``` php\n'user_oidc' =\u003e [\n    'single_logout' =\u003e false,\n],\n```\n\n### Backchannel logout\n\n[OpenId backchannel logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) is supported by this app.\nYou just have to configure 2 settings for the OpenId client (on the provider side, Keycloak for example):\n1. Backchannel Logout URL: If your Nextcloud base URL is https://my.nextcloud.org\nand your OpenId provider identifier (on the Nextcloud side) is \"myOidcProvider\"\nset the backchannel Logout URL to\nhttps://my.nextcloud.org/index.php/apps/user_oidc/backchannel-logout/myOidcProvider .\nThis URL is provided for each provider in the OpenID Connect admin settings.\n2. Enable the \"Backchannel Logout Session Required\" setting.\n\n### Auto provisioning\n\nBy default, this app provisions the users with the information contained in the OIDC token\nwhich means it gets the user information (such as the display name or the email) from the ID provider.\nThis also means that user_oidc takes care of creating the users when they first log in.\n\nIt is possible to disable auto provisioning to let other user backends (like LDAP)\ntake care of user creation and attribute mapping.\nThis leaves user_oidc to only take care of authentication.\n\nAuto provisioning can be disabled in `config.php`:\n``` php\n'user_oidc' =\u003e [\n    'auto_provision' =\u003e false,\n],\n```\n\n:warning: When relying on the LDAP user backend for user provisioning, you need to adjust the\n\"Login Attributes\" section and the Expert tab's \"Internal Username\" value of your LDAP settings.\nEven if LDAP does not handle the login process,\nthe user_oidc app will trigger an LDAP search when logging in to make sure the user is created if it was\nnot synced already.\nSo it is essential that:\n* the OpenID Connect \"User ID mapping\" attribute matches the LDAP Expert tab's \"Internal Username\".\nThe attribute names can be different but their values should match. Do not change the LDAP configuration,\nsimply adapt the OpenID Connect provider configuration.\n* the OpenID Connect \"User ID mapping\" attribute can be used in the LDAP login query\ndefined in the \"Login Attributes\" tab.\n\nIn other words, make sure that your OpenID Connect provider's \"User ID mapping\" setting is set to an attribute\nwhich provides the same values as the LDAP attribute set in \"Internal Username\" in your LDAP settings.\n\n#### Soft auto provisioning\n\nIf you have existing users managed by another backend (local or LDAP users for example) and you want them to be managed\nby user_oidc but you still want user_oidc to auto-provision users\n(create new users when they are in the Oidc IdP but not found in any other user backend),\nthis is possible with **soft** auto provisioning.\n\nThere is a `soft_auto_provision` system config flag that is enabled by default and is effective only if `auto_provision`\nis enabled.\n``` php\n'user_oidc' =\u003e [\n    'auto_provision' =\u003e true, // default: true\n    'soft_auto_provision' =\u003e true, // default: true\n],\n```\n\n* When `soft_auto_provision` is enabled\n  * If the user already exists in another backend, we don't create a new one in the user_oidc backend.\n    We update the information (mapped attributes) of the existing user.\n    If the user does not exist in another backend, we create it in the user_oidc backend\n* When `soft_auto_provision` is disabled\n  * We refuse Oidc login of users that already exist in other backends\n\n#### Soft auto provisioning without user creation\n\nYou might want soft auto provisioning but prevent user_oidc to create users,\nmeaning you want user_oidc to accept connection only for users that already exist in Nextcloud and are managed by other\nuser backend BUT you still want user_oidc to set the user information according to the OIDC mapped attributes.\n\nFor that, there is a `disable_account_creation` system config flag that is false by default and is effective\nonly if `auto_provision` and `soft_auto_provision` are enabled\nis enabled.\n``` php\n'user_oidc' =\u003e [\n    'auto_provision' =\u003e true, // default: true\n    'soft_auto_provision' =\u003e true, // default: true\n    'disable_account_creation' =\u003e true, // default: false\n],\n```\n\n### 4 Provisioning scenarios\n\n* Create users if they don't exist\n    * Accept connection of existing users (from other backends) and update their attributes:\n      ``` php\n      'user_oidc' =\u003e [\n          'auto_provision' =\u003e true, // default: true\n          'soft_auto_provision' =\u003e true, // default: true\n      ],\n      ```\n    * Do not accept connection of users existing in other backends:\n\t  ``` php\n\t  'user_oidc' =\u003e [\n\t\t  'auto_provision' =\u003e true, // default: true\n\t\t  'soft_auto_provision' =\u003e false, // default: true\n\t  ],\n\t  ```\n* Do not create users if they don't exist\n    * Update attributes of existing users (create by user_oidc or any other backend):\n\t  ``` php\n\t  'user_oidc' =\u003e [\n\t  \t'auto_provision' =\u003e true, // default: true\n\t  \t'soft_auto_provision' =\u003e true, // default: true\n\t  \t'disable_account_creation' =\u003e true, // default: false\n\t  ],\n\t  ```\n    * Do not update attributes of existing users:\n      ``` php\n      'user_oidc' =\u003e [\n          'auto_provision' =\u003e false, // default: true\n      ],\n      ```\n\n### Pre-provisioning\n\nIf you need the users to exist before they authenticate for the first time\n(because you want other users to be able to share files with them, for example)\nyou can pre-provision them with the user_oidc API:\n\n``` bash\ncurl -H \"ocs-apirequest: true\" -u admin:admin -X POST -H \"content-type: application/json\" \\\n  -d '{\"providerId\":2,\"userId\":\"new_user\",\"displayName\":\"New User\",\"email\":\"new@user.org\",\"quota\":\"5GB\"}' \\\n  https://my.nextcloud.org/ocs/v2.php/apps/user_oidc/api/v1/user\n```\n\nOnly the `providerId` and `userId` parameters are mandatory.\n\nYou can also delete users managed by user_oidc with this API endpoint:\n\n``` bash\ncurl -H \"ocs-apirequest: true\" -u admin:admin -X DELETE\n  https://my.nextcloud.org/ocs/v2.php/apps/user_oidc/api/v1/user/USER_ID\n```\n\n### Bearer token validation\n\nThe OIDC tokens used to make API call to Nextcloud might have been generated by an external entity.\nIt is possible that they don't contain the user ID attribute. In this case, this attribute\ncan be requested to the provider's `userinfo` endpoint.\n\nAdd this to `config.php` to enable such extra validation step:\n``` php\n'user_oidc' =\u003e [\n    'userinfo_bearer_validation' =\u003e true,\n],\n```\n\nIf you only want the token to be validated against the `userinfo` endpoint,\nit is possible to disable the classic \"self-encoded\" validation:\n``` php\n'user_oidc' =\u003e [\n    'userinfo_bearer_validation' =\u003e true,\n    'selfencoded_bearer_validation' =\u003e false,\n],\n```\n\nIf you want to ask the [OIDC Identity Provider app](https://apps.nextcloud.com/apps/oidc) to validate a bearer token:\n``` php\n'user_oidc' =\u003e [\n    'oidc_provider_bearer_validation' =\u003e true,\n],\n```\nThis requires the OIDC Identity Provider app \u003e= v1.4.0 . Access tokens and JWT tokens can be validated.\n\n### Group provisioning\n\nYou can configure each provider:\n* Toggle group provisioning (creates nonexisting groups on login)\n* Set the group whitelist regular expression (nonmatching groups will be kept untouched)\n* Toggle login restriction to people who don't belong to any whitelisted group\n\nThis can be done in the graphical settings, in the \"OpenID Connect\" admin settings section or with the occ command to create/update providers:\n\n```\nsudo -u www-data php /var/www/nextcloud/occ user_oidc:provider demoprovider \\\n                --clientid=\"...\" --clientsecret=\"***\" --discoveryuri=\"...\" \\\n                --group-provisioning=1 --group-whitelist-regex='/\u003cregex\u003e/' --group-restrict-login-to-whitelist=1\n```\n\n### Disable audience and azp checks\n\nThe `audience` and `azp` token claims will be checked when validating a login ID token.\nOnly the `audience` will be checked when validating a Bearer token.\nYou can disable these checks with these config values (in config.php):\n``` php\n'user_oidc' =\u003e [\n    'login_validation_audience_check' =\u003e false,\n    'login_validation_azp_check' =\u003e false,\n    'selfencoded_bearer_validation_audience_check' =\u003e false,\n],\n```\n\n### Disable the user search by email\n\nThis app can stop matching users (when a user search is performed in Nextcloud) by setting this config.php value:\n``` php\n'user_oidc' =\u003e [\n    'user_search_match_emails' =\u003e false,\n],\n```\n\n## Building the app\n\nRequirements for building:\n- Node.js 14\n- NPM 7\n- PHP\n- composer\n\nThe app uses [krankerl](https://github.com/ChristophWurst/krankerl) to build the release archive from the git repository.\nThe release will be put into `build/artifacts/` when running the `krankerl package`.\n\nThe app can also be built without krankerl by manually running:\n```\ncomposer install --no-dev -o\nnpm ci\nnpm run build\n```\n\nOn Ubuntu 20.04, a possible way to get build working is with matching npm and node versions is:\n```\nsudo apt-get remove nodejs\nsudo curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -\nsudo apt-get install nodejs\nsudo npm install -g npm@7\n```\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud%2Fuser_oidc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextcloud%2Fuser_oidc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud%2Fuser_oidc/lists"}