diff --git a/docs/docs/client-examples/grist.md b/docs/docs/client-examples/grist.md new file mode 100644 index 0000000..0302220 --- /dev/null +++ b/docs/docs/client-examples/grist.md @@ -0,0 +1,22 @@ +--- +id: grist +--- + +# Grist + +## Pocket ID Setup +1. In Pocket-ID create a new OIDC Client, name it i.e. `Grist` +2. Set the callback url to: `https:///oauth2/callback` +3. In Grist (Docker/Docker Compose/etc), set these environment variables: + +```ini +GRIST_OIDC_IDP_ISSUER="https:///.well-known/openid-configuration" +GRIST_OIDC_IDP_CLIENT_ID="" +GRIST_OIDC_IDP_CLIENT_SECRET="" +GRIST_OIDC_SP_HOST="https://" +GRIST_OIDC_IDP_SCOPES="openid email profile" # Default +GRIST_OIDC_IDP_SKIP_END_SESSION_ENDPOINT=true # Default=false, needs to be true for Pocket Id b/c end_session_endpoint is not implemented +GRIST_OIDC_IDP_END_SESSION_ENDPOINT="https:///api/webauthn/logout" # Only set this if GRIST_OIDC_IDP_SKIP_END_SESSION_ENDPOINT=false and you need to define a custom endpoint +``` +4. Also ensure that the `GRIST_DEFAULT_EMAIL` env variable is set to the same email address as your user profile within Pocket ID +5. Start/Restart Grist \ No newline at end of file diff --git a/docs/docs/client-examples/netbox.md b/docs/docs/client-examples/netbox.md new file mode 100644 index 0000000..24a76cf --- /dev/null +++ b/docs/docs/client-examples/netbox.md @@ -0,0 +1,46 @@ +--- +id: netbox +--- + +# Netbox + +**This guide does not currently show how to map groups in netbox from OIDC claims** + +The following example variables are used, and should be replaced with your actual URLS. + +- netbox.example.com (The url of your netbox instance.) +- id.example.com (The url of your Pocket ID instance.) + +## Pocket ID Setup + +1. In Pocket-ID create a new OIDC Client, name it i.e. `Netbox`. +2. Set a logo for this OIDC Client if you would like too. +3. Set the callback URL to: `https://netbox.example.com/oauth/complete/oidc/`. +4. Copy the `Client ID`, and the `Client Secret` for use in the next steps. + +## Netbox Setup + +This guide assumes you are using the git based install of netbox. + +1. On your netbox server navigate to `/opt/netbox/netbox/netbox` +2. Add the following to your `configuration.py` file: + +```python +# Remote authentication support +REMOTE_AUTH_ENABLED = True +REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth' +REMOTE_AUTH_HEADER = 'HTTP_REMOTE_USER' +REMOTE_AUTH_USER_FIRST_NAME = 'HTTP_REMOTE_USER_FIRST_NAME' +REMOTE_AUTH_USER_LAST_NAME = 'HTTP_REMOTE_USER_LAST_NAME' +REMOTE_AUTH_USER_EMAIL = 'HTTP_REMOTE_USER_EMAIL' +REMOTE_AUTH_AUTO_CREATE_USER = True +REMOTE_AUTH_DEFAULT_GROUPS = [] +REMOTE_AUTH_DEFAULT_PERMISSIONS = {} + +SOCIAL_AUTH_OIDC_ENDPOINT = 'https://id.example.com' +SOCIAL_AUTH_OIDC_KEY = '' +SOCIAL_AUTH_OIDC_SECRET = '' +LOGOUT_REDIRECT_URL = 'https://netbox.example.com' +``` + +3. Save the file and restart netbox: `sudo systemctl start netbox netbox-rq` \ No newline at end of file diff --git a/docs/docs/client-examples/pgadmin.md b/docs/docs/client-examples/pgadmin.md new file mode 100644 index 0000000..a8c3c12 --- /dev/null +++ b/docs/docs/client-examples/pgadmin.md @@ -0,0 +1,42 @@ +--- +id: pgadmin +--- + +# pgAdmin + +The following example variables are used, and should be replaced with your actual URLS. + +- pgadmin.example.com (The url of your pgAdmin instance.) +- id.example.com (The url of your Pocket ID instance.) + +## Pocket ID Setup + +1. In Pocket-ID create a new OIDC Client, name it i.e. `pgAdmin`. +2. Set a logo for this OIDC Client if you would like too. +3. Set the callback URL to: `https://pgadmin.example.com/oauth2/authorize`. +4. Copy the `Client ID`, `Client Secret`, `Authorization URL`, `Userinfo URL`, `Token URL`, and `OIDC Discovery URL` for use in the next steps. + +# pgAdmin Setup + +1. Add the following to the `config_local.py` file for pgAdmin: + +**Make sure to replace https://id.example.com with your actual Pocket ID URL** + +```python +AUTHENTICATION_SOURCES = ['oauth2', 'internal'] # This keeps internal authentication enabled as well as oauth2 +OAUTH2_AUTO_CREATE_USER = True +OAUTH2_CONFIG = [{ + 'OAUTH2_NAME' : 'pocketid', + 'OAUTH2_DISPLAY_NAME' : 'Pocket ID', + 'OAUTH2_CLIENT_ID' : '', + 'OAUTH2_CLIENT_SECRET' : '', + 'OAUTH2_TOKEN_URL' : 'https://id.example.com/api/oidc/token', + 'OAUTH2_AUTHORIZATION_URL' : 'https://id.example/authorize', + 'OAUTH2_API_BASE_URL' : 'https://id.example.com', + 'OAUTH2_USERINFO_ENDPOINT' : 'https://id.example.com/api/oidc/userinfo', + 'OAUTH2_SERVER_METADATA_URL' : 'https://id.example.com/.well-known/openid-configuration', + 'OAUTH2_SCOPE' : 'openid email profile', + 'OAUTH2_ICON' : 'fa-openid', + 'OAUTH2_BUTTON_COLOR' : '#fd4b2d' # Can select any color you would like here. +}] +``` diff --git a/docs/docs/client-examples/portainer.md b/docs/docs/client-examples/portainer.md new file mode 100644 index 0000000..fabc0fc --- /dev/null +++ b/docs/docs/client-examples/portainer.md @@ -0,0 +1,38 @@ +--- +id: portainer +--- + +# Portainer + +**This requires Portainers Business Edition** + +The following example variables are used, and should be replaced with your actual URLS. + +- portainer.example.com (The url of your Portainer instance.) +- id.example.com (The url of your Pocket ID instance.) + +## Pocket ID Setup + +1. In Pocket-ID create a new OIDC Client, name it i.e. `Portainer`. +2. Set a logo for this OIDC Client if you would like too. +3. Set the callback URL to: `https://portainer.example.com/`. +4. Copy the `Client ID`, `Client Secret`, `Authorization URL`, `Userinfo URL`, and `Token URL` for use in the next steps. + +# Portainer Setup + +- While initally setting up OAuth in Portainer, its recommended to keep the `Hide internal authentication prompt` set to `Off` incase you need a fallback login +- This guide does **NOT** cover how to setup group claims in Portainer. + +1. Open the Portainer web interface and navigate to: `Settings > Authentication` +2. Select `Custom OAuth Provider` +3. Paste the `Client ID` from Pocket ID into the `Client ID` field in Portainer. +4. Paste the `Client Secret` from Pocket ID into the `Client Secret` field in Portainer. +5. Paste the `Authorization URL` from Pocket ID into the `Authorization URL` field in Portainer. +6. Paste the `Token URL` from Pocket ID into the `Access token URL` field in Portainer. +7. Paste the `Userinfo URL` from Pocket ID into the `Resource URL` field in Portainer. +8. Set the `Redirect URL` to `https://portainer.example.com` +9. Set the `Logout URL` to `https://portainer.example.com` +10. Set the `User identifier` field to `preferred_username`. (This will use the users username vs the email) +11. Set the `Scopes` field to: `email openid profile` +12. Set `Auth Style` to `Auto detect` +13. Save the settings and test the new OAuth Login. diff --git a/docs/docs/client-examples/proxmox.md b/docs/docs/client-examples/proxmox.md new file mode 100644 index 0000000..4f508de --- /dev/null +++ b/docs/docs/client-examples/proxmox.md @@ -0,0 +1,30 @@ +--- +id: proxmox +--- + +# Proxmox + +The following example variables are used, and should be replaced with your actual URLS. + +- proxmox.example.com (The url of your proxmox instance.) +- id.example.com (The url of your Pocket ID instance.) + +## Pocket ID Setup + +1. In Pocket-ID create a new OIDC Client, name it i.e. `Proxmox`. +2. Set a logo for this OIDC Client if you would like too. +3. Set the callback URL to: `https://proxmox.example.com`. +4. Copy the `Client ID`, and the `Client Secret` for use in the next steps. + +## Proxmox Setup + +1. Open the Proxmox Console and navigate to: `Datacenter - Realms` +2. Add a new `Open ID Connect Server` Realm +3. Enter `https://id.example.com` for the `Issuer URL` +4. Enter a name for the realm of your choice ie. `PocketID` +5. Paste the `Client ID` from Pocket ID into the `Client ID` field in Proxmox. +6. Paste the `Client Secret` from Pocket ID into the `Client Key` field in Proxmox. +7. You can check the `Default` box if you want this to be the deafult realm proxmox uses when signing in. +8. Check the `Autocreate Users` checkbox. (This will automaitcally create users in Proxmox if they dont exsist.) +9. Select `username` for the `Username Claim` dropdown (This is personal preference and controls how the username is shown, ie: `username = username@PocketID` or `email = username@example@PocketID`). +10. Leave the rest as defaults and click `OK` to save the new realm. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 93a488b..d1dbfa5 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -59,12 +59,17 @@ const sidebars: SidebarsConfig = { slug: "client-examples", }, items: [ + "client-examples/cloudflare-zero-trust", + "client-examples/grist", "client-examples/hoarder", "client-examples/jellyfin", - "client-examples/vikunja", + "client-examples/netbox", "client-examples/open-webui", + "client-examples/pgadmin", + "client-examples/portainer", + "client-examples/proxmox", "client-examples/semaphore-ui", - "client-examples/cloudflare-zero-trust", + "client-examples/vikunja", ], }, {